Lifecycle
completed and failed are final. A task does not change after it gets there.
To know when a task ends, poll GET /v1/tasks/{taskId} every few seconds, or pass a webhookUrl. See Webhooks.
Create a task
GET /v1/models lists the countries and languages. A model with countries: null runs in every country of the list.
Retry safely with an Idempotency-Key
A network error can hide whether a task was created. To retry without paying twice, send anIdempotency-Key header:
- The first request creates the task:
201 Created. - The same key with the same body returns that same task:
200 OK. It is charged once. - The same key with a different body is refused:
409with the codeidempotency_key_reused.details.taskIdnames the first task.
List tasks
GET /v1/tasks lists your organization’s tasks, newest first. It filters by status, model, apiKeyId, from, to, and q (a task id or words of the prompt). status=running means queued or processing.
A list gives up to limit tasks (50 by default, 100 at most), without their results. To read the next page, pass nextCursor as cursor. A null nextCursor means the last page.