Get task status
Look up a single asynchronous job by its task ID to see where it stands and, once it wraps up, pull back the finished result.
Overview
Jobs submitted through the async endpoints run in the background, so you check on them by polling this route with the task ID you received at submission time. Each response reports a status that moves through a small set of stages:
| Status | Meaning |
|---|---|
QUEUED | The job has been accepted and is waiting for a worker to pick it up. |
PROCESSING | The job is currently running. |
COMPLETED | The job finished cleanly; the response object holds the full result. |
FAILED | The job could not finish; the response object may carry error details. |
While a task is still QUEUED or PROCESSING, the payload reports only the current status and an empty response. As soon as it reaches COMPLETED or FAILED, the response object is populated with the outcome.
Path parameters
| Field | Type | Description |
|---|---|---|
taskId | string (uuid) | Identifier of the task you want to inspect, returned when the job was created. |
Headers
| Field | Type | Description |
|---|---|---|
Authorization | string | Required. Bearer credential in the form Bearer <token>, where the token is your API key. |
Response fields
| Field | Type | Description |
|---|---|---|
task | object | Summary of the job, common to every async task response. |
task.id | string (uuid) | Unique identifier of the task. |
task.taskType | string | Which extractor the job runs, for example CHATGPT. |
task.status | string | Current stage: QUEUED, PROCESSING, COMPLETED, or FAILED. |
task.priority | integer | Scheduling priority assigned to the job. |
task.createdAt | string (ISO 8601) | Timestamp of when the task was created. |
task.idempotencyKey | string | Client-supplied key used to guard against duplicate submissions. |
credits | object | Credit accounting for the task. |
credits.creditsToCharge | integer | Credits the job is expected to cost. |
credits.creditsCharged | integer | null | Credits actually billed; null until the job settles. |
response | object | Full result of the job, present only once it is COMPLETED or FAILED. |
Response example
{
"task": {
"id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
"taskType": "CHATGPT",
"status": "QUEUED",
"priority": 1,
"createdAt": "2026-04-09T15:00:00.000Z",
"idempotencyKey": "batch-chatgpt-001"
},
"credits": {
"creditsToCharge": 10,
"creditsCharged": null
},
"response": {}
}Notes
Finished and failed tasks stay available for 24 hours after they settle. Within that window you can re-fetch the complete result by task ID; once the window closes, the record and its stored response are removed for good. Any HTML URLs handed back inside a result also lapse 24 hours after they are generated, independent of the task's own retention.
Poll on a sensible interval rather than in a tight loop, and treat a 404 as a task that either never existed or has already aged out. For help, reach us at [email protected].