Skip to main content
A job is one request for one token. The API runs jobs in the background, so you submit a job and then read it.

​
Job states

A job can fail from queued too. For example, it fails with JOB_TIMEOUT when it waits too long, or with JOB_CANCELLED when you cancel it.

​
The job object

​
Wait for a result

Use long polling. Add wait (0 to 30 seconds) to GET /v1/jobs/{id}. The API holds the request open until the job finishes or the wait ends, then returns the job as it is.
  • If status is still queued or running, send the request again.
  • Without wait, the API returns the job at once. If you poll this way, wait about one second between requests.
A poll returns HTTP 200 for a failed job too. Always read data.status.

​
Time limits

A job must finish within 120 seconds of its submission, including the time it waits in the queue. A job that runs out of time fails with JOB_TIMEOUT.

​
Cancel a job

Send DELETE /v1/jobs/{id}.
  • A queued or running job stops. It then reads as failed with the code JOB_CANCELLED.
  • A done or failed job is deleted from the service.
The response holds the job as it was left.

​
Retention

The service keeps a finished job for 5 minutes. After that, GET /v1/jobs/{id} returns 404 with JOB_NOT_FOUND. Read the token before then. Jobs are kept in memory. If the service restarts, it loses the jobs that it holds. A job that is still queued when the service stops fails with SHUTTING_DOWN. Submit it again.

​
List jobs

GET /v1/jobs returns the jobs that the service holds, newest first. Filter with status, and set limit (1 to 200, default 50). The list never includes tokens. To get a token, read the job by its ID.