Task API

The Task API manages task execution — polling, updating, logging, and queue management. All endpoints use the base path /api/tasks.

Get Task

GET /api/tasks/{taskId}

Returns the task details for a given task ID.

curl 'http://localhost:8080/api/tasks/a1b2c3d4-5678-90ab-cdef-111111111111'

Response 200 OK

{
  "taskType": "my_task",
  "status": "COMPLETED",
  "referenceTaskName": "my_task_ref",
  "retryCount": 0,
  "seq": 1,
  "startTime": 1700000001000,
  "endTime": 1700000003000,
  "updateTime": 1700000003000,
  "pollCount": 1,
  "taskId": "a1b2c3d4-5678-90ab-cdef-111111111111",
  "workflowInstanceId": "3a5b8c2d-1234-5678-9abc-def012345678",
  "inputData": {"key": "value"},
  "outputData": {"result": "success"},
  "workerId": "worker-host-1"
}

Poll and Update Tasks

These endpoints are used by workers to poll for tasks and update their results. They are typically called by the SDK, not manually.

Poll for a Task

GET /api/tasks/poll/{taskType}?workerid=&domain=

Polls for a single task of the given type. Returns 204 No Content if no task is available.

Parameter	Description	Required
`taskType`	Task type to poll for	Yes
`workerid`	Identifier for the worker polling	No
`domain`	Task domain. See Task Domains.	No

curl 'http://localhost:8080/api/tasks/poll/my_task?workerid=worker-1'

Response 200 OK — returns a task object (same format as Get Task above), or 204 No Content if no tasks are queued.

Batch Poll

GET /api/tasks/poll/batch/{taskType}?count=1&timeout=100&workerid=&domain=

Polls for multiple tasks in a single request. This is a long poll — the connection waits until timeout or at least 1 task is available.

Parameter	Description	Default
`taskType`	Task type to poll for	—
`count`	Maximum number of tasks to return	`1`
`timeout`	Long poll timeout in milliseconds	`100`
`workerid`	Worker identifier	—
`domain`	Task domain	—

# Poll for up to 5 tasks, wait up to 1 second
curl 'http://localhost:8080/api/tasks/poll/batch/my_task?count=5&timeout=1000&workerid=worker-1'

Response 200 OK — returns a list of task objects, or an empty list if no tasks are available.

[
  {
    "taskType": "my_task",
    "status": "IN_PROGRESS",
    "taskId": "task-uuid-1",
    "workflowInstanceId": "workflow-uuid-1",
    "inputData": {"key": "value1"}
  },
  {
    "taskType": "my_task",
    "status": "IN_PROGRESS",
    "taskId": "task-uuid-2",
    "workflowInstanceId": "workflow-uuid-2",
    "inputData": {"key": "value2"}
  }
]

Update Task

POST /api/tasks

Updates the result of a task execution. Returns the task ID.

curl -X POST 'http://localhost:8080/api/tasks' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflowInstanceId": "3a5b8c2d-1234-5678-9abc-def012345678",
    "taskId": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "status": "COMPLETED",
    "outputData": {
      "result": "processed successfully",
      "recordCount": 42
    }
  }'

Request body fields:

Field	Description	Required
`workflowInstanceId`	Workflow execution ID	Yes
`taskId`	Task ID	Yes
`status`	`IN_PROGRESS`, `COMPLETED`, `FAILED`, or `FAILED_WITH_TERMINAL_ERROR`	Yes
`outputData`	JSON map of output data	No
`reasonForIncompletion`	Reason for failure (when status is `FAILED`)	No
`callbackAfterSeconds`	Callback delay — task will be put back in queue after this time	No
`logs`	List of log entries to append	No

Response 200 OK — returns the task ID as plain text.

Update Task V2

POST /api/tasks/update-v2

Updates a task and returns the next available task to be processed — combining an update and poll in one call. Returns 204 No Content if no next task is available.

curl -X POST 'http://localhost:8080/api/tasks/update-v2' \
  -H 'Content-Type: application/json' \
  -d '{
    "workflowInstanceId": "3a5b8c2d-1234-5678-9abc-def012345678",
    "taskId": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "status": "COMPLETED",
    "outputData": {"result": "done"}
  }'

Response 200 OK — returns the next task object, or 204 No Content if no tasks are queued.

Update Task by Reference Name

POST /api/tasks/{workflowId}/{taskRefName}/{status}?workerid=

Updates a task using the workflow ID and task reference name instead of the task ID. This is useful for completing WAIT or HUMAN tasks from external systems.

Parameter	Description	Required
`workflowId`	Workflow execution ID	Yes
`taskRefName`	Task reference name in the workflow	Yes
`status`	`IN_PROGRESS`, `COMPLETED`, `FAILED`, or `FAILED_WITH_TERMINAL_ERROR`	Yes
`workerid`	Worker identifier	No

Request body: JSON map of output data.

# Complete a WAIT task with output data
curl -X POST 'http://localhost:8080/api/tasks/3a5b8c2d.../wait_for_approval/COMPLETED' \
  -H 'Content-Type: application/json' \
  -d '{"approved": true, "approver": "jane@example.com"}'

Response 200 OK — no response body.

Update Task by Reference Name (Synchronous)

POST /api/tasks/{workflowId}/{taskRefName}/{status}/sync?workerid=

Same as above, but returns the updated workflow after the task update is processed. Useful for synchronous execution patterns where you need the workflow state immediately after updating a task.

curl -X POST 'http://localhost:8080/api/tasks/3a5b8c2d.../wait_for_signal/COMPLETED/sync' \
  -H 'Content-Type: application/json' \
  -d '{"signal": "proceed"}'

Response 200 OK — returns the full workflow execution object.

Task Logs

Add a Task Log

POST /api/tasks/{taskId}/log

Adds an execution log entry to a task. Request body: log message as a plain string.

curl -X POST 'http://localhost:8080/api/tasks/a1b2c3d4.../log' \
  -H 'Content-Type: text/plain' \
  -d 'Processing started for batch #42'

Response 200 OK — no response body.

Get Task Logs

GET /api/tasks/{taskId}/log

Returns execution logs for a task. Returns 204 No Content if no logs exist.

curl 'http://localhost:8080/api/tasks/a1b2c3d4.../log'

Response 200 OK

[
  {
    "log": "Processing started for batch #42",
    "taskId": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "createdTime": 1700000001000
  },
  {
    "log": "Batch #42 completed: 100 records processed",
    "taskId": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "createdTime": 1700000003000
  }
]

Queue Management

Endpoint	Method	Description
`/queue/all`	`GET`	Get pending task counts for all queues
`/queue/all/verbose`	`GET`	Get detailed queue info including per-shard counts
`/queue/size`	`GET`	Get queue size for a specific task type
`/queue/sizes`	`GET`	(Deprecated) Get queue sizes for task types. Use `/queue/size` instead.
`/queue/requeue/{taskType}`	`POST`	Requeue pending tasks of a given type

Get Queue Size

GET /api/tasks/queue/size?taskType=&domain=&isolationGroupId=&executionNamespace=

Returns the queue depth for a specific task type, optionally filtered by domain and isolation group.

curl 'http://localhost:8080/api/tasks/queue/size?taskType=my_task'

Response 200 OK

Get All Queue Sizes

GET /api/tasks/queue/all

Returns a map of task type to pending count for all queues.

curl 'http://localhost:8080/api/tasks/queue/all'

Response 200 OK

{
  "my_task": 5,
  "http_task": 0,
  "email_task": 12
}

Get All Queue Details (Verbose)

GET /api/tasks/queue/all/verbose

Returns detailed queue information including per-shard counts.

curl 'http://localhost:8080/api/tasks/queue/all/verbose'

Response 200 OK

{
  "my_task": {
    "size": 5,
    "shards": {"0": 3, "1": 2}
  }
}

Requeue Pending Tasks

POST /api/tasks/queue/requeue/{taskType}

Requeues all pending tasks of the specified type. Useful for recovery after worker issues.

curl -X POST 'http://localhost:8080/api/tasks/queue/requeue/my_task'

Response 200 OK — returns the number of tasks requeued.

Poll Data

Get Poll Data for a Task Type

GET /api/tasks/queue/polldata?taskType=

Returns the last poll data for a given task type — useful for monitoring worker health and activity.

curl 'http://localhost:8080/api/tasks/queue/polldata?taskType=my_task'

Response 200 OK

[
  {
    "queueName": "my_task",
    "domain": null,
    "workerId": "worker-host-1",
    "lastPollTime": 1700000005000
  }
]

Get Poll Data for All Task Types

GET /api/tasks/queue/polldata/all

Returns the last poll data for all task types.

curl 'http://localhost:8080/api/tasks/queue/polldata/all'

Response 200 OK — returns a list of poll data objects (same format as above) for all task types.

Search Tasks

All search endpoints support the same query parameters:

Parameter	Description	Default
`start`	Page offset	`0`
`size`	Number of results	`100`
`sort`	Sort order: `<field>:ASC` or `<field>:DESC`	—
`freeText`	Full-text search query	`*`
`query`	SQL-like where clause	—

Search (Summary)

GET /api/tasks/search?start=0&size=100&sort=&freeText=&query=

Returns SearchResult<TaskSummary> — lightweight results.

# Find failed tasks for a specific workflow type
curl 'http://localhost:8080/api/tasks/search?query=workflowType%3D%27order_processing%27+AND+status%3D%27FAILED%27&size=10'

# Free-text search
curl 'http://localhost:8080/api/tasks/search?freeText=timeout'

Response 200 OK

{
  "totalHits": 3,
  "results": [
    {
      "taskId": "task-uuid",
      "taskType": "my_task",
      "referenceTaskName": "my_task_ref",
      "workflowId": "workflow-uuid",
      "workflowType": "order_processing",
      "status": "FAILED",
      "startTime": "2024-01-15T10:30:00Z",
      "updateTime": "2024-01-15T10:30:05Z",
      "executionTime": 5000
    }
  ]
}

Search V2 (Full)

GET /api/tasks/search-v2?start=0&size=100&sort=&freeText=&query=

Returns SearchResult<Task> — full task objects including input/output data.

External Storage

GET /api/tasks/externalstoragelocation?path=&operation=&payloadType=

Get the URI for external task payload storage. See External Payload Storage.

curl 'http://localhost:8080/api/tasks/externalstoragelocation?path=task/output&operation=WRITE&payloadType=TASK_OUTPUT'

Response 200 OK

{
  "uri": "s3://conductor-payloads/task/output/...",
  "path": "task/output/..."
}