List tasks

List tasks in the caller’s workspace. Cursor-paginated, newest-first. Filter by agent, status, creation date range, and title substring.

GET /api/v1/tasks

List tasks

cURL

curl --request GET \
  --url https://agents.nanonets.com/api/v1/tasks \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "pending",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "agent_name": "<string>",
      "title": "<string>",
      "data_fields": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "logical_field_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "key": "<string>",
          "value": "<unknown>",
          "key_type": "string",
          "description": "<string>"
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Authorizations

Authorization · string · header · required

Workspace API key issued from the web app. Pass as Authorization: Bearer YOUR_API_KEY.

Query Parameters

cursor · string

Opaque pagination cursor returned by a previous response in next_cursor. Omit on the first request.

limit · integer · default: 20

Maximum number of items to return. Defaults to 20; max 100.

Required range: 1 <= x <= 100

agent_id · string<uuid>

Only return tasks created from this agent version. Each publish creates a new version id, so this filter misses tasks run by older versions — use agent_group_id to match an agent across all of its versions.

agent_group_id · string<uuid>

Only return tasks created from any version of this agent. The group id is stable across publishes (see GET /api/v1/agents/{agent_id}/versions).

status · string

Comma-separated list of statuses to include (pending, queued, running, waiting_for_input, awaiting_review, completed, failed, stopped).

created_after · string<date-time>

ISO-8601 timestamp; only tasks created at or after this instant.

created_before · string<date-time>

ISO-8601 timestamp; only tasks created at or before this instant.

q · string

Substring match against task title (case-insensitive).

source · enum<string> · default: production

Which task bucket to list.

• production (default) — live tasks. This is every task in the workspace regardless of how it was started (API, trigger, schedule, chat, …) except test tasks; it is the endpoint's long-standing default, unchanged.
• test — only runs created with source: "test".
• all — both of the above.

Any other value returns 400.

Available options: production, test, all

include_data_fields · boolean · default: false

When true, each task carries a data_fields array holding that task's agent data fields (the values shown as columns in the task list in the app).

Omitted from the response entirely unless you ask for it, so the default payload is unchanged.

Two things to know before relying on these values:

• They are extracted by a model when the task completes, not asserted by the platform. A field can be absent, or filled with a plausible but wrong value, on a task whose input never contained it.
• They can contain content extracted from the documents a task processed.

Any non-boolean value returns 400, including a bare ?include_data_fields with no value — so a malformed request can never be mistaken for tasks that have no data fields.

If the fields cannot be loaded, the request fails with 500; an empty data_fields always means the task genuinely has none.

Requests that return data fields are recorded in your workspace's audit log (task.data_fields_read), naming the tasks whose values were read. The default list, which returns no extracted values, is not recorded.

Response

200

application/json

Paginated list of tasks.

data · object[] · required

Show child attributes

has_more · boolean · required

next_cursor · string | null