---
title: "Get document ingestion status"
method: GET
path: "/v1/projects/{project_id}/documents/{document_id}/status"
tags: ["Documents"]
---

# Get document ingestion status

`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`)

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.

## Path parameters

- `document_id` string, required

## Response `200`

Document ingestion status

- DocumentStatusRecord
  - `id` string: Document ID
  - `status` 'pending' | 'processing' | 'ready' | 'failed': Ingestion lifecycle state.
  - `chunk_count` integer: 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_chunks` integer, nullable: Planned total number of chunks, known once chunking begins. `null` until then. Used as the denominator for `progress`.
  - `total_pages` integer, 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).
  - `progress` integer, 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.
  - `error` StoredError: Why a resource's work failed, in the shape of an error response's `error` without `hint` and `docs_url`. Every `error` field a resource records carries it, so `code` can be read without first checking the type of `error`.
    - `code` string, required: A key from the server's ERROR_CODES registry, documented on the Error Codes page. `INTERNAL_ERROR`, with the message `Internal Server Error`, records an unexpected failure whose detail reaches the server log only.
    - `message` string, required
    - `meta` object: The failure's own structured context, when it names any.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Document not found

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)