> ## Documentation Index > Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List tasks > List tasks in the caller's workspace. Cursor-paginated, newest-first. Filter by agent, status, creation date range, and title substring. ## OpenAPI ````yaml GET /api/v1/tasks openapi: 3.1.0 info: title: Nanonets Agents Platform — Public API version: 1.0.0 summary: >- Programmatically run AI agents, send follow-up messages, fetch results, and update agent prompts. description: > The Nanonets Agents Platform Public API lets you trigger agents, stream task progress, and integrate agent outputs into your own systems. ## Authentication All requests must include a workspace API key as a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` Workspace API keys are minted from the web app under **Settings → API Keys**. Each key is scoped to a single workspace; requests against agents or tasks outside that workspace return `403`. ## Lifecycle A typical integration is three calls: 1. `POST /v1/agents/{agent_id}/run` — start a task. Returns a `task_id` immediately. 2. Poll `GET /v1/tasks/{task_id}` until `status` is a terminal value (`completed`, `failed`, or `stopped`), **or** wait until it reaches `waiting_for_input` to respond with `POST /v1/tasks/{task_id}/message`. 3. `GET /v1/tasks/{task_id}/summary` for the final answer, or `/result` for the full reasoning trace. ## Errors Every error response is `{"error": ""}`. The HTTP status indicates the class: | Status | Meaning | |--------|---------| | 400 | Malformed request (bad UUID, missing required field, file too large) | | 401 | Missing or invalid API key | | 403 | API key is valid but the agent/task belongs to a different workspace | | 404 | Agent or task not found | | 500 | Server error — safe to retry with backoff | contact: name: Nanonets Support url: https://nanonets.com/support license: name: Proprietary servers: - url: https://agents.nanonets.com description: Production security: - bearerAuth: [] tags: - name: Agents description: Manage agents — create, list, update, run, and version. - name: Tasks description: >- Inspect task status, fetch results, list and cancel tasks, and send follow-up messages. paths: /api/v1/tasks: get: tags: - Tasks summary: List tasks description: | List tasks in the caller's workspace. Cursor-paginated, newest-first. Filter by agent, status, creation date range, and title substring. operationId: listTasks parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Limit' - name: agent_id in: query description: Only return tasks created from this agent. schema: type: string format: uuid - name: status in: query description: > Comma-separated list of statuses to include (`pending`, `queued`, `running`, `waiting_for_input`, `awaiting_review`, `completed`, `failed`, `stopped`). schema: type: string - name: created_after in: query description: ISO-8601 timestamp; only tasks created at or after this instant. schema: type: string format: date-time - name: created_before in: query description: ISO-8601 timestamp; only tasks created at or before this instant. schema: type: string format: date-time - name: q in: query description: Substring match against task title (case-insensitive). schema: type: string responses: '200': description: Paginated list of tasks. content: application/json: schema: $ref: '#/components/schemas/ListTasksResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/ServerError' components: parameters: Cursor: name: cursor in: query required: false description: > Opaque pagination cursor returned by a previous response in `next_cursor`. Omit on the first request. schema: type: string Limit: name: limit in: query required: false description: Maximum number of items to return. Defaults to 20; max 100. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: ListTasksResponse: type: object required: - data - has_more properties: data: type: array items: $ref: '#/components/schemas/TaskSummary' next_cursor: type: - string - 'null' has_more: type: boolean TaskSummary: type: object description: Slim task representation for list responses (no feed). required: - task_id - agent_id - status - created_at - updated_at properties: task_id: type: string format: uuid agent_id: type: string format: uuid agent_name: type: string description: Convenience field — name of the agent that produced this task. status: $ref: '#/components/schemas/TaskStatus' title: type: - string - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object required: - error properties: error: type: string description: Human-readable error message. examples: - Invalid agent_id format TaskStatus: type: string description: > Lifecycle status of a task. - `pending` — created, not yet picked up - `queued` — held back by admission control (agent at concurrent-task limit) - `running` — being processed by the worker - `waiting_for_input` — agent called `ask_user`; reply with `POST /tasks/{id}/message` - `awaiting_review` — agent is paused for human approval of a sensitive step - `completed` — terminal: finished successfully - `failed` — terminal: errored out - `stopped` — terminal: cancelled by a user or system enum: - pending - queued - running - waiting_for_input - awaiting_review - completed - failed - stopped responses: BadRequest: description: >- Malformed request — invalid UUID, missing required field, or oversized file. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: Unexpected server error. Safe to retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | Workspace API key issued from the web app. Pass as `Authorization: Bearer YOUR_API_KEY`. ````