---
title: "Poll task."
method: GET
path: "/api/v1/projects/{projectId}/tasks/{taskId}"
tags: ["Tasks"]
---

# Poll task.

`GET /api/v1/projects/{projectId}/tasks/{taskId}`

## Request

- Base URL: `https://app.customgpt.ai`
- URL: `https://app.customgpt.ai/api/v1/projects/{projectId}/tasks/{taskId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/poll-the-people/apis/customgpt-ai/docs/api/v1/projects/:projectId/tasks/:taskId/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `projectId` integer, required
- `taskId` string, required

## Response `200`

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.

- object
  - `status` 'error' | 'success': The status of the response
  - `data` object
    - `task` Task
      - `id` string: Task ID
      - `project_id` integer: Agent ID this task belongs to
      - `name` string: Task name
      - `created_at` string, date-time: When the task was created
      - `updated_at` string, date-time: When the task was last updated
    - `status` 'processing' | 'awaiting_tool_results' | 'completed': `processing` while the session is running; `awaiting_tool_results` when the agent is waiting for function results (submit them via `POST /tasks/{taskId}/tool-outputs`); `completed` once done. Returns 404 if the result has expired or the job never completed.
    - `events` TaskEvent[]: Stream events flushed since the last poll. Empty array when no new events are available or when `status` is `completed`. Each element follows the TaskEvent schema.
      - `type` 'task' | 'progress' | 'artifact' | 'error': Event type. `task` - agent started a step. `progress` - agent wrote a text chunk. `artifact` - agent generated a file. `error` - session failed.
      - `data` object: Event payload. Shape depends on `type`: `task` → `{ current_task: string }`. `progress` → `{ message: string }`. `artifact` → `{ id, filename, download_url }`. `error` → `{ message: string }`.
    - `result` object, nullable: `null` while `status` is `processing`. When `status` is `awaiting_tool_results`, contains `tool_calls` — OpenAI-format function calls to execute and answer via `POST /tasks/{taskId}/tool-outputs`. When `status` is `completed`, contains `message_id` — use it to fetch the full response via `GET /tasks/{taskId}/messages/{messageId}`. That endpoint reads from durable storage and remains available after this poll result is consumed or expires.
      - `message_id` integer: ID of the PromptHistory record containing the final response. Use with `GET /tasks/{taskId}/messages/{messageId}` to retrieve the full content — it is the durable record and remains available after the poll result is consumed or its 2h TTL expires.
      - `tool_calls` object[]: Pending function calls (OpenAI format) when `status` is `awaiting_tool_results`. Each has `id`, `type: "function"`, and `function.name` / `function.arguments` (JSON-encoded string).
        - `id` string
        - `type` 'function'
        - `function` object
          - `name` string
          - `arguments` string

## Other responses

- `400`: Bad Argument
- `401`: API Token is either missing or invalid
- `404`: Agent not found
- `429`: Too many requests. You have exceeded your API rate limit.
- `500`: Internal Server Error

## Changes

- **2026-11-03** `77aab4354382`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/poll-the-people/apis/customgpt-ai/changes/api/v1/projects/:projectId/tasks/:taskId/get.md)

---

[API](https://skmtc.dev/poll-the-people/apis/customgpt-ai.md) - [All operations](https://skmtc.dev/poll-the-people/apis/customgpt-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/poll-the-people/apis/customgpt-ai/revisions/77aab4354382?raw)