POpoll-the-people
Tasks

Poll task.

Changed on

Returns the current processing state of a task.

While the task is running, returns status: processing with any stream events flushed since the last poll.

When the agent needs one of the functions supplied via tools, returns status: awaiting_tool_results with result.tool_calls (OpenAI format). Execute the functions and submit their results via POST /tasks/{taskId}/tool-outputs; the session then resumes. This status persists across polls (for up to 2 hours) until outputs are submitted.

Once the session completes, returns status: completed with result.message_id pointing to the final message.

The completed result is consumed on first read and is held for at most 2 hours after completion — subsequent polls return 404, so persist the result on first successful read. If you miss the result window or have already consumed it, fetch the persisted history via GET /tasks/{taskId}/messages instead.

get/api/v1/projects/{projectId}/tasks/{taskId}

Request

Path parameters

projectIdinteger required

The unique identifier of the agent.

taskIdstring required

The task ID. This is the value returned in data.id when you create a task via POST /tasks.

Response

Task state snapshot.

The events array contains all events flushed from the Redis queue since the last poll (empty when the queue is drained). When status is completed the result object is populated.

status'error' | 'success'

The status of the response

Example response

{
  "status": "success",
  "data": {
    "task": {
      "id": "f1b9aaf0-5e4e-11eb-ae93-0242ac130002",
      "project_id": 1,
      "name": "Analyse this document",
      "created_at": "Monday, 01-Jan-24 12:00:00 UTC",
      "updated_at": "Monday, 01-Jan-24 12:00:00 UTC"
    },
    "status": "processing",
    "events": [],
    "result": {
      "message_id": 4821,
      "tool_calls": [
        {
          "id": "call_8f14e45fceea167a5a36dedd4bea2543",
          "function": {
            "name": "track_order",
            "arguments": "{\"order_id\": \"ORD-1042\"}"
          }
        }
      ]
    }
  }
}

Changes