> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apistable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query a task

> Read each result as it finishes, with its own status and cost.

> API preview: generation providers are not connected. An authenticated request can return 503 without creating a task or charging credits.

## Follow the whole lifecycle

| State | Meaning |
| - | - |
| queued / running | Waiting for capacity or generating. |
| falling\_back | An eligible failed item is switching routes. |
| reconciliation\_required | The upstream result is unknown; do not resubmit. |
| succeeded | All target items succeeded. |
| partially\_succeeded | All items are final, and some succeeded. |
| failed / cancelled | Final failure, or a confirmed cancellation where supported. |

## Read individual items

The same parent can contain low-cost and official successes. Never assume the final item’s channel applies to every result. This simplified example omits output URLs, errors, and timestamps.

```bash theme={null}
{
  "task_id": "task_example",
  "status": "partially_succeeded",
  "output_count": 4,
  "counts": {
    "succeeded": 3,
    "failed": 1,
    "cancelled": 0,
    "pending": 0
  },
  "billing": {
    "initial_reserved_credits": 240,
    "charged_credits": 100,
    "released_credits": 140,
    "remaining_reserved_credits": 0
  },
  "items": [
    {
      "index": 0,
      "item_id": "item_1",
      "status": "succeeded",
      "final_channel_type": "third_party",
      "charged_credits": 20
    },
    {
      "index": 1,
      "item_id": "item_2",
      "status": "succeeded",
      "final_channel_type": "third_party",
      "charged_credits": 20
    },
    {
      "index": 2,
      "item_id": "item_3",
      "status": "succeeded",
      "final_channel_type": "official",
      "charged_credits": 60
    },
    {
      "index": 3,
      "item_id": "item_4",
      "status": "failed",
      "final_channel_type": null,
      "charged_credits": 0
    }
  ]
}
```

## Poll without creating extra work

Query the existing task ID at intervals, honor Retry-After, and add backoff when a task takes longer. Read already completed items while other items are running. Do not hold a new generation request open as a polling mechanism.

Download before the returned expires\_at. File expiry does not change the historical success state or automatically refund credits.


## OpenAPI

````yaml openapi.json GET /v1/tasks/{id}
openapi: 3.1.0
info:
  title: APIstable API preview
  version: 0.1.0-preview
  description: >-
    Current implemented HTTP surface. / 当前已实现的 HTTP 接口。 Models and quote prices
    are illustrative. Real providers and paid generation are not connected. POST
    /v1/tasks and /v1/chat/completions return 503 provider_not_configured after
    authentication and applicable validation; no credits are reserved or
    charged. Live 202 acceptance, provider callbacks, SSE, idempotent task
    creation, and full model capability adapters remain future integration work.
    Website login sessions are separate from application API keys.
servers:
  - url: https://apistable.com
    description: APIstable API
security: []
tags:
  - name: Models
  - name: Quotes
  - name: Tasks
  - name: Credits
  - name: LLM
paths:
  /v1/tasks/{id}:
    get:
      tags:
        - Tasks
      summary: Read a stored task / 查询任务
      description: >-
        Requires usage:read. The task must belong to the API key’s account.
        Response uses public snake_case fields, independent of console
        presentation. Real provider execution is not yet enabled.
      operationId: getTask
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Stored task ID / 已存任务 ID
      responses:
        '200':
          description: Stored task and per-item billing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          description: invalid_api_key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: insufficient_scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found; task absent or not owned by this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Task:
      type: object
      required:
        - task_id
        - model
        - modality
        - status
        - output_count
        - fallback
        - created_at
        - duration_ms
        - counts
        - billing
        - items
      properties:
        task_id:
          type: string
        model:
          type: string
        modality:
          type: string
        status:
          type: string
          description: >-
            Operation status. Possible states include queued, running,
            falling_back, reconciliation_required, succeeded,
            partially_succeeded, failed, and cancelled.
        output_count:
          type: integer
          minimum: 1
          maximum: 4
        fallback:
          type: boolean
        created_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          minimum: 0
          description: Completed duration; currently zero for unfinished tasks.
        counts:
          type: object
          required:
            - succeeded
            - failed
            - cancelled
            - pending
          properties:
            succeeded:
              type: integer
              minimum: 0
            failed:
              type: integer
              minimum: 0
            cancelled:
              type: integer
              minimum: 0
            pending:
              type: integer
              minimum: 0
        billing:
          type: object
          required:
            - initial_reserved_credits
            - charged_credits
            - released_credits
            - remaining_reserved_credits
          properties:
            initial_reserved_credits:
              type: number
              minimum: 0
              description: Credits, not USD. / 积分，非美元。
            charged_credits:
              type: number
              minimum: 0
              description: Credits, not USD. / 积分，非美元。
            released_credits:
              type: number
              minimum: 0
              description: Credits, not USD. / 积分，非美元。
            remaining_reserved_credits:
              type: number
              minimum: 0
              description: Credits, not USD. / 积分，非美元。
        items:
          type: array
          items:
            $ref: '#/components/schemas/GenerationItem'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    GenerationItem:
      type: object
      required:
        - item_id
        - index
        - status
        - final_channel_type
        - charged_credits
        - attempts
        - outputs
      properties:
        item_id:
          type: string
        index:
          type: integer
          minimum: 0
        status:
          type: string
        final_channel_type:
          type:
            - string
            - 'null'
          description: Selected successful route only; null for unfinished or failed items.
        charged_credits:
          type: number
          minimum: 0
          description: Credits, not USD. / 积分，非美元。
        attempts:
          type: array
          items:
            type: object
            required:
              - attempt_id
              - channel_type
              - status
              - duration_ms
            properties:
              attempt_id:
                type: string
              channel_type:
                type: string
              status:
                type: string
              duration_ms:
                type: integer
                minimum: 0
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/Output'
    Output:
      type: object
      required:
        - output_id
        - type
        - status
        - assets
        - metadata
        - expires_at
      properties:
        output_id:
          type: string
        type:
          type: string
        status:
          type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        title:
          type:
            - string
            - 'null'
        assets:
          type: array
          items:
            type: object
            required:
              - role
              - url
            properties:
              role:
                type: string
              url:
                type: string
        metadata:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIstable API key
      description: >-
        API key beginning as_. Keep on the server. Scope permissions are checked
        separately.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.