Documents

Get document ingestion status

Returns a lightweight ingestion status payload for polling — status, chunk_count, total_pages, and (when failed) error. Unlike GET /documents/{document_id}, it never returns the assembled chunk content, so it is cheap to poll on large documents. A document whose ingestion has stalled (no progress past the configured timeout) is transitioned to failed with error=INGESTION_TIMEOUT on read.

get/v1/projects/{project_id}/documents/{document_id}/status

Request

Base URL: https://api.naturali.ai
URL: https://api.naturali.ai/v1/projects/{project_id}/documents/{document_id}/status
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

document_idstring required

Example:doc_V1StGXR8Z5jdHi6B

Document ID

Response

Document ingestion status

idstring

Document ID

status'pending' | 'processing' | 'ready' | 'failed'

Ingestion lifecycle state.

chunk_countinteger

Number of chunks currently indexed for this document (a live count). Grows while status=processing and equals the final total once ready; 0 while pending.

total_chunksinteger nullable

Planned total number of chunks, known once chunking begins. null until then. Used as the denominator for progress.

total_pagesinteger nullable

Number of source pages extracted. Only known after extraction, so it is null until status is ready or failed (not the same as zero pages).

progressinteger nullable

Ingestion progress as a percentage (chunk_count / total_chunks). 0 while pending, climbs while processing (capped at 99), 100 when ready, and null when failed or not yet computable.

Example response

{
  "id": "doc_V1StGXR8Z5jdHi6B",
  "status": "ready",
  "chunk_count": 10,
  "total_chunks": 12,
  "total_pages": 12,
  "progress": 100,
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.