Create a Task

Create a task

Contents

• Overview
• Version-specific information
• Permissions and Authentication
• Headers
• JSON body parameters
• Sample request
• Sample response
• Sample request with segment filter
• Possible error responses

Overview

• Endpoint URL: https://{Services API hostname}/tasks
• Request method: HTTP POST
• Request Content-Type: application/json
• Response Content-Type: application/json
• Auth required: yes

Create a new task on the Services API. The task will be scheduled to run at the time specified in trigger.once.

Version-specific information

The following version-specific changes apply to this endpoint:

Version	Change details
N/A	N/A

Permissions and Authentication

This endpoint requires chain-scoped authentication on the Services API. See the authentication page for more details on authentication methods. The following authentication types are permitted:

• Privileged authentication: the use of privileged authentication is permitted for this endpoint.
• Admin authentication: the use of admin authentication is permitted. The performing user needs to have the appropriate access level for the chain.

Headers

The following headers can/must be passed to the API call:

Parameter	Description
N/A	N/A

JSON body parameters

The following JSON parameters can be passed in the request body:

Parameter	Type	Required	Description
chain	integer	required	The chain ID for which the task should run.
desc	string	required	A description of the task (for reference purposes).
target	object	required	Defines what the task does. See Target parameters in the Tasks overview.
trigger	object	required	Defines when the task runs and optional filtering. See Scheduling and triggers in the Tasks overview.
debug	string	optional	Debug string for diagnostic purposes.

Sample request

curl -X POST 'https://{Services API hostname}/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_ID:ACCESS_TOKEN_SECRET' \
  -d '{
    "chain": 1764,
    "desc": "Wallet ledger export for analytics warehouse",
    "target": {
      "action": "export",
      "export_index": "wallet-ledger",
      "export_format": "csv"
    },
    "trigger": {
      "once": "2026-05-26T12:00:00Z"
    }
  }'

Sample response

Returns the created task object with HTTP status 201 Created. The response includes a Location header with the task URL. See Task object structure for a description of all fields.

{
  "id": 12345,
  "chain": 1764,
  "desc": "Wallet ledger export for analytics warehouse",
  "state": {
    "code": "READY",
    "last_run_date": "0001-01-01T00:00:00Z",
    "last_modified": "2026-05-26T11:59:00Z",
    "created_date": "2026-05-26T11:59:00Z"
  },
  "trigger": {
    "once": "2026-05-26T12:00:00Z"
  },
  "target": {
    "action": "export",
    "export_index": "wallet-ledger",
    "export_format": "csv"
  },
  "logs": null,
  "debug": "",
  "version": 2,
  "result": ""
}

Sample request with segment filter

curl -X POST 'https://{Services API hostname}/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS_TOKEN_ID:ACCESS_TOKEN_SECRET' \
  -d '{
    "chain": 1764,
    "desc": "Users created in the last 24 hours",
    "target": {
      "action": "export",
      "export_index": "users",
      "export_format": "csv"
    },
    "trigger": {
      "once": "2026-05-26T12:00:00Z",
      "segment": {
        "entity": "people",
        "index": "users",
        "join": "all",
        "chain_id": 1764,
        "rules": [
          {
            "field_name": "created_date",
            "field_type": "date",
            "operator": "relative_less_than",
            "time_factor": "day",
            "time_amount": 1
          }
        ]
      }
    }
  }'

Possible error responses

The following represents a list of possible error responses for this endpoint:

Condition	Description
Missing required fields	chain, target, or trigger is missing from the request body.
Invalid chain	The specified chain ID is not valid or the user has no access.
Invalid export index	The target.export_index value is not a supported index.
Invalid segment rules	A segment rule contains an unsupported operator or invalid field.
Authentication failure	No valid authentication provided or insufficient permissions.