Async jobs

Most fileAI work takes longer than an HTTP request should: OCR, extraction, an agent’s answer, a forensics scan. The API accepts the work, hands you an id straight away, and lets you either poll that id or receive a callback when it settles. There are four kinds of long-running work, each with its own id and status values.

How it works

Work	Started by	Id	Poll	Callback
Upload processing	`POST /v1/files/upload` (and batch, multipart)	`uploadId`	`GET /v1/uploads/{uploadId}`	`callbackURL` (payload)
Document jobs	`POST /v1/extract`, `/v1/split`, `/v1/classify`	`job_…`	`GET /v1/jobs/{job_id}`	`callback_url` on the request
Agent jobs	`POST /v1/agent/sessions/{session_id}/ask`	`sajob_…`	`GET /v1/jobs/{job_id}`	The API key’s default callback URL
Forensics runs	`POST /v1/forensics`	`run_id`	`GET /v1/forensics/runs/{run_id}`	None: poll only

Submit calls for jobs and runs return 202 Accepted with the id and a poll_url. poll_url is a URI reference: if it comes back without a scheme and host, resolve it against the host you called.

Polling or callbacks

Polling is the source of truth; a callback is a speed-up. No callback is retried, so a callback your endpoint misses is gone, while the job or upload itself stays readable.

Use a callback to learn about settled work quickly.
Keep polling as a fallback for anything you have not heard back about.
Make your handler idempotent: a job or upload can be reported more than once.
Treat a callback as a prompt to fetch the job or upload with your API key, not as the result itself.

Upload callbacks and job callbacks are delivered differently:

	Upload callbacks	Document job callbacks	Agent job callbacks
Where it goes	`callbackURL` on the upload; single and batch uploads fall back to the API key’s default callback URL, multipart uploads do not	`callback_url` on the request only	The API key’s default callback URL
When it is sent	Once per processing step	When the job settles	When the job settles, and again if a provisional failure resolves
Payload	Small step event (Processing callbacks)	The job, as polling returns it (below)	The job, as polling returns it (below)
Attempts	One `POST`, never retried	One `POST`, never retried	One `POST`, never retried
Timeout	None set by fileAI	10 seconds	10 seconds
Signature	None	May carry `X-Signature`, which you cannot verify yet	May carry `X-Signature`, which you cannot verify yet

Forensics runs have no callback: poll them.

Uploads

An upload is tracked by its uploadId. GET /v1/uploads/{uploadId} returns:

Field	Description
`statuses`	Processing steps so far, each with `step`, `status`, `timestamp` and, on failure, a human-readable `errorReason`.
`files`	The documents produced from the upload, in the same shape as `GET /v1/files`. Each has its own `status`.
`fileType`	The uploaded file’s type.
`aiProcessingProvider`	The engine that actually processed the file.

Each step has one of these statuses (step names are listed on Processing callbacks):

Step `status`	Meaning
`waiting`	The step is queued.
`processing`	The step is running.
`completed`	The step finished. The upload is done when `processing_finished` is `completed`.
`error`	The step failed. `errorReason` says why, when it is known.

A ZIP upload returns one entry per extracted file in files, and answers 207 when some extracted files succeeded and others failed.

The statuses list is held for 10 minutes after the most recent step. After that it can come back empty. For a finished upload, read each document’s status in files (for example processed or action_required) instead.

Document jobs

POST /v1/extract, /v1/split and /v1/classify each take one document and return a job with a job_ id:

{
  "job_id": "job_4b7e8d4c1fa0b39f2c1a6d0e8b7f5a21",
  "status": "queued",
  "created_at": "2026-09-25T02:14:00.000Z",
  "poll_url": "https://api.orion.file.ai/prod/v1/jobs/job_4b7e8d4c1fa0b39f2c1a6d0e8b7f5a21"
}

Polling it returns kind: "extraction" and one of these statuses:

`status`	Meaning
`queued`	Not settled. Poll again.
`succeeded`	Final. `result` holds the output.
`failed`	Final. `error.code` and `error.detail` describe the failure.

usage (pages, credits) appears once the job has settled, and client_ref echoes the value you submitted. See Extract, split and classify for request fields and result shapes. To get a callback, send callback_url with the request. The API key’s default callback URL is not used for document jobs; agent jobs use only that default.

Agent jobs

Each question asked in an agent session is a job with a sajob_ id, polled on the same GET /v1/jobs/{job_id} route. It returns kind: "agent" and uppercase statuses:

`status`	Meaning
`QUEUED`, `RUNNING`	Not ready. Poll again.
`COMPLETED`	Final. `result.answer` holds the answer.
`STOPPED`	Final. A turn stopped early; `result.answer` holds the partial answer.
`FAILED`	Final, except that `error.code` `SUPERAGENT_RUN_STALE` is provisional and can still move to `COMPLETED` or `STOPPED`.

GET /v1/jobs/{job_id} serves both kinds. Branch on kind before reading anything else: the statuses and result differ.

Forensics runs

A fileForensics run checks a file that is already stored in your workspace. It is not a job: it does not appear on GET /v1/jobs/{job_id}, and it has no callback.

`status`	Meaning
`queued`, `running`	In progress. Poll again.
`complete`	Final. Each detector’s result is under `forensics`.
`error`	Final. The run failed, or was replaced by a retry.

A run that is stuck can be re-run with POST /v1/forensics/runs/{run_id}/retry, which returns a new run_id to poll. GET /v1/forensics/files/{file_id} returns the newest run for a file, including runs started at upload. See Run status for details.

Callbacks

Document and agent job callbacks share one shape, mirroring what polling returns:

{
  "event": "extraction.job.settled",
  "job_id": "job_4b7e8d4c1fa0b39f2c1a6d0e8b7f5a21",
  "status": "succeeded",
  "created_at": "2026-09-25T02:14:00.000Z",
  "updated_at": "2026-09-25T02:14:09.000Z",
  "client_ref": "shipment-8812",
  "result": { "documents": [] },
  "error": null,
  "usage": { "pages": 6, "credits": 6 }
}

	Document jobs	Agent jobs
`event`	`extraction.job.settled`	`superagent.job.settled`
`usage`	Included	Not included
Sent when	The job settles	The job settles, and again if a provisional `SUPERAGENT_RUN_STALE` failure later resolves

Delivery is a single POST with Content-Type: application/json and a 10-second timeout. It is not retried, whatever your endpoint returns.

Job callbacks may carry X-Signature and X-Timestamp headers. There is no per-key secret you can verify them with yet, so treat every callback as unauthenticated: fetch the job with your API key before acting on it.

Processing callbacks

Step-by-step events for uploads.

Extract, split and classify

Submit one document and poll its job.

Agent sessions

Ask questions and poll sajob_ jobs.

Idempotent requests

Retry submits without creating duplicate work.

Get started

Products

Build

Go live

How it works

Polling or callbacks

Uploads

Document jobs

Agent jobs

Forensics runs

Callbacks

Processing callbacks

Extract, split and classify

Agent sessions

Idempotent requests

​How it works

​Polling or callbacks

​Uploads

​Document jobs

​Agent jobs

​Forensics runs

​Callbacks

​Related

Processing callbacks

Extract, split and classify

Agent sessions

Idempotent requests

How it works

Polling or callbacks

Uploads

Document jobs

Agent jobs

Forensics runs

Callbacks

Related