GET /v1/files/{file_id}/processing — Atom Files Developers

← API referenceFile intelligence · API access unavailable

API REFERENCE / FILE INTELLIGENCE

`GET` /v1/files/{file_id}/processing

Read detected file type and per-output processing progress for a content version.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Path	`file_id`	string	Yes	Stable Atom file ID.
Query	`version_id`	string	Recommended	Pin the processing report to an immutable content version.

Request example

Example request

GET /v1/files/file_789/processing?version_id=ver_012
Authorization: Bearer <scoped token>

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid version ID.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`404 Not Found`	File or version is not visible to this caller.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`file_id`	string	file_789
`version_id`	string	ver_012
`policy_revision`	string	proc_rev_007
`detected_type`	object	{…}
`detected_type.media_type`	string	application/pdf
`detected_type.family`	string (extensible)	document Examples · extensible`imageaudiovideodocumentspreadsheet`
`detected_type.detection`	string	content_and_metadata
`outputs`	object[]	[3 shown]
`outputs[].kind`	string (extensible)	page_ocr Examples · extensible`thumbnailpage_ocrtranscriptpage_summarydocument_summaryvisual_embedding`
`outputs[].state`	string (enum)	ready Allowed values · closed enum`not_applicabledisabledqueuedrunningpartialreadyfailedstale`
`outputs[].completed_units`	integer	12
`outputs[].total_units`	integer	12
`outputs[].artifact_count`	integer	12
`outputs[].updated_at`	string (date-time)	2026-10-20T18:02:00Z

Response example

Example response

200 OK
Content-Type: application/json

{
  "file_id": "file_789",
  "version_id": "ver_012",
  "policy_revision": "proc_rev_007",
  "detected_type": {
    "media_type": "application/pdf",
    "family": "document",
    "detection": "content_and_metadata"
  },
  "outputs": [
    {
      "kind": "page_ocr",
      "state": "ready",
      "completed_units": 12,
      "total_units": 12,
      "artifact_count": 12,
      "updated_at": "2026-10-20T18:02:00Z"
    },
    {
      "kind": "page_summary",
      "state": "partial",
      "completed_units": 4,
      "total_units": 12,
      "artifact_count": 4,
      "updated_at": "2026-10-20T18:03:00Z"
    },
    {
      "kind": "document_summary",
      "state": "queued",
      "completed_units": 0,
      "total_units": 1,
      "artifact_count": 0,
      "updated_at": "2026-10-20T18:03:00Z"
    }
  ]
}

How it works

There is no single file-wide complete flag. Every enabled output reports its own state: not_applicable, disabled, queued, running, partial, ready, failed, or stale. A new file version has independent processing state; old results must not appear current.