Async generation status

Returns the status of an async PDF generation task. Use this when the original request was made with async_mode: true.

Signature

GET /api/v1/generate/status/{task_id}

Permissions

API key scope: read or higher. Caller must own the originating generation request.

Path parameters

Name	Type	Description
`task_id`	string	Task ID returned by `POST /generate/pdf` in async mode.

Example

curl https://api.simplyfill.app/v1/generate/status/tsk_98e2b... \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY"

const task = await client.generate.status('tsk_98e2b...')
if (task.status === 'completed') {
  console.log(task.result.download_url)
}

task = client.generate.status("tsk_98e2b...")
if task.status == "completed":
    print(task.result["download_url"])

Response

{
  "task_id": "tsk_98e2b...",
  "status": "completed",
  "progress": 100,
  "started_at": "2026-05-17T15:01:11Z",
  "completed_at": "2026-05-17T15:01:13Z",
  "result": {
    "file_id": "f_2nB9d4Z...",
    "download_url": "https://api.simplyfill.app/v1/generate/download/f_2nB9d4Z...",
    "expires_at": "2026-05-18T15:01:13Z"
  },
  "error": null
}

Status values

`status`	Meaning
`pending`	Queued, not yet started.
`processing`	Worker has the task. `progress` ticks 0 → 100.
`completed`	PDF is ready. `result.download_url` is set.
`failed`	Generation failed. `error` describes why.
`cancelled`	Cancelled via `DELETE /generate/cancel/{task_id}`.

Polling guidance

Poll no more than once every 2 seconds. Most jobs finish in under 5 seconds.
Prefer the generation.completed webhook over polling — it eliminates request volume entirely and counts against your hourly limit zero times instead of N.

To abandon an in-flight task, call DELETE /api/v1/generate/cancel/{task_id}. The task transitions to cancelled if it hadn't already started; if it had, the result is discarded on completion. Cancellation does not refund the request against your hourly rate limit, but does refund the monthly PDF quota.

Errors

Status	`error` code	Cause
`404`	`task_not_found`	No task with this ID, or you don't own it.

Async status