API Reference
Job Status
Poll the status and result of an async job.
Authorization
bearerAuth AuthorizationBearer <token>
OAuth2 client credentials flow. Token obtained from /oauth2/token on the auth host.
In: header
Path Parameters
job_id*string
Header Parameters
X-Correlation-Id*string
Caller-supplied correlation ID. Propagated end-to-end and returned in responses and audit logs.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://api.eu.faction.ai/v1/jobs/job_01JZP4XYZ123" \ -H "X-Correlation-Id: 8f3c-b21"{
"job_id": "job_01JZP4XYZ123",
"status": "processing",
"created_at": "2026-04-29T14:20:00Z"
}{
"error_code": "EXPIRED_TOKEN",
"message": "Bearer token expired at 2026-04-29T13:00:00Z.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "JOB_NOT_FOUND",
"message": "Job 'job_01JZP4XYZ123' was not found or has expired.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}{
"error_code": "INTERNAL_ERROR",
"message": "An unexpected error occurred.",
"correlation_id": "8f3c-b21",
"request_id": "req_01JZP4..."
}Async lifecycle
- Caller sends
Prefer: respond-asyncon a synchronous endpoint. - Faction returns
202 Acceptedwith ajob_idandstatus_url. - Caller polls the status URL, or registers a
Faction-Callback-Urlfor webhook delivery. - Job statuses:
queued→processing→complete(withresult) orfailed(witherror). - Jobs remain queryable for 24 hours after completion.
Callbacks are retried up to 5 times with exponential backoff if the caller's webhook does not return a 2xx response.