Jobs

Poll the status of a generic asynchronous job. Several endpoints return a job descriptor (202 Accepted) and defer the actual work to the background — use this endpoint to follow it to completion. For the general async pattern, see Conventions → Async jobs.

Derived vs. enqueued. Most jobs are processed by the generic worker. Some long-running operations (campaign build steps, workspace regenerate) instead report derived status computed from live resource readiness when you poll — they behave identically to the caller. Batch generation does not use this endpoint; poll the list instead (see Lists).

Get job status

GET /api/v1/jobs/:id

Returns the current state of an async job in the API key's workspace.

Path parameters

Example request

curl -X GET "https://app.machfive.io/api/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "id": "job-uuid",
  "type": "workspace.import.document",
  "status": "completed",
  "progress": null,
  "result": { "status": "completed", "fields_updated": 7 },
  "error": null,
  "created_at": "2026-06-14T12:00:00.000Z",
  "updated_at": "2026-06-14T12:01:30.000Z"
}

Note on import-job failures. Some jobs (notably workspace.import.document) finish with job status: "completed" even when the underlying work did not succeed — the outcome is carried in result.status. For these, check result.status (e.g. "failed") and result.error/result.fields_updated rather than the top-level status/error fields (which stay completed/null).

Error responses