Query a task

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

GET /v1/tasks/{id}

Read a stored task / 查询任务

cURL

curl --request GET \
  --url https://apistable.com/v1/tasks/{id} \
  --header 'Authorization: Bearer <token>'

200

{
  "task_id": "<string>",
  "model": "<string>",
  "modality": "<string>",
  "status": "<string>",
  "output_count": 2,
  "fallback": true,
  "created_at": "2023-11-07T05:31:56Z",
  "duration_ms": 1,
  "counts": {
    "succeeded": 1,
    "failed": 1,
    "cancelled": 1,
    "pending": 1
  },
  "billing": {
    "initial_reserved_credits": 1,
    "charged_credits": 1,
    "released_credits": 1,
    "remaining_reserved_credits": 1
  },
  "items": [
    {
      "item_id": "<string>",
      "index": 1,
      "status": "<string>",
      "final_channel_type": "<string>",
      "charged_credits": 1,
      "attempts": [
        {
          "attempt_id": "<string>",
          "channel_type": "<string>",
          "status": "<string>",
          "duration_ms": 1
        }
      ],
      "outputs": [
        {
          "output_id": "<string>",
          "type": "<string>",
          "status": "<string>",
          "expires_at": "2023-11-07T05:31:56Z",
          "assets": [
            {
              "role": "<string>",
              "url": "<string>"
            }
          ],
          "metadata": {},
          "title": "<string>"
        }
      ]
    }
  ]
}

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.

{
  "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.

Authorizations

Authorization · string · header · required

API key beginning as_. Keep on the server. Scope permissions are checked separately.

Path Parameters

id · string · required

Stored task ID / 已存任务 ID

Response

200

application/json

Stored task and per-item billing

task_id · string · required

model · string · required

modality · string · required

status · string · required

Operation status. Possible states include queued, running, falling_back, reconciliation_required, succeeded, partially_succeeded, failed, and cancelled.

output_count · integer · required

Required range: 1 <= x <= 4

fallback · boolean · required

created_at · string<date-time> · required

duration_ms · integer · required

Completed duration; currently zero for unfinished tasks.

Required range: x >= 0

counts · object · required

Show child attributes

billing · object · required

Show child attributes

items · object[] · required

Show child attributes