Skip to main content
A task is one prompt, sent to one model, in one country and one language.

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 an Idempotency-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: 409 with the code idempotency_key_reused. details.taskId names the first task.
Use a key that names the work, for example the prompt set, the date, the model and the country. A key is 1 to 255 characters.

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.
To get a result, read the task by its id.