Jobs

Score and rewrite requests create asynchronous jobs. Creation returns 202 with a job id and an initial state. Poll the typed job endpoint until the job reaches a terminal state.

Public job states:

queued
running
succeeded
failed
cancelled

Create responses are intentionally small:

{
  "jobId": "job_000224",
  "state": "queued"
}

A queued job response contains only the id and state:

{
  "jobId": "job_000225",
  "state": "queued"
}

A failed job response includes a public error summary:

{
  "jobId": "job_000226",
  "state": "failed",
  "error": {
    "code": "worker_failed",
    "message": "The job failed while processing.",
    "retryable": false
  }
}

List routes return metadata only, not item-level results or customer text:

{
  "items": [
    {
      "jobId": "job_000226",
      "state": "failed",
      "createdAt": "2026-06-30T00:00:00Z",
      "updatedAt": "2026-06-30T00:05:00Z",
      "completedAt": "2026-06-30T00:05:00Z",
      "itemCount": 1,
      "inputBytes": 96,
      "resultSummary": null,
      "errorSummary": {
        "code": "worker_failed",
        "message": "The job failed while processing.",
        "retryable": false
      }
    }
  ],
  "nextCursor": null
}

Use the matching typed endpoint for each job kind:

POST /v1/score-jobs
GET  /v1/score-jobs
GET  /v1/score-jobs/{jobId}
POST /v1/score-jobs/{jobId}/cancel

POST /v1/rewrite-jobs
GET  /v1/rewrite-jobs
GET  /v1/rewrite-jobs/{jobId}
POST /v1/rewrite-jobs/{jobId}/cancel

Typed routes do not return jobs from the other kind.

Bulk Results Retrieval

To fetch many job results without one GET per job, pass includeResults=true to the list routes. Each succeeded job summary then carries its full public results array, so a submitted batch is retrieved in one or two calls (list, then follow nextCursor when present):

GET /v1/score-jobs?includeResults=true&limit=100
GET /v1/rewrite-jobs?includeResults=true&limit=100

Queued, running, failed, and cancelled jobs never carry results; failed jobs still carry errorSummary. Cursors are bound to the includeResults mode they were issued with, so a cursor from a results-included listing is rejected with 400 invalid_cursor on a plain listing (and vice versa).

Completion Webhooks

Register a webhookUrl on job creation to receive a signed notification when the job reaches a terminal succeeded or failed state instead of polling. See Webhooks for the payload and signature verification.