---
title: "List Documents"
method: GET
path: "/datastores/{datastore_id}/documents"
tags: ["/datastores/{id}/documents"]
---

# List Documents

`GET /datastores/{datastore_id}/documents`

Get list of documents in a given `Datastore`, including document `id`, `name`, and ingestion job `status`.

Performs `cursor`-based pagination if the number of documents exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores/{datastore_id}/documents` call to retrieve the next set of documents.

## Path parameters

- `datastore_id` string, uuid, required — Datastore ID of the datastore to retrieve documents for

## Query parameters

- `limit` integer — Maximum number of documents to return
- `cursor` string — Cursor from the previous call to list documents, used to retrieve the next set of results
- `ingestion_job_status` DocumentStatusEnum[] — Filters documents whose ingestion job status matches (one of) the provided status(es).
- `uploaded_after` string, date-time — Filters documents uploaded at or after specified timestamp.
- `uploaded_before` string, date-time — Filters documents uploaded at or before specified timestamp.
- `document_name_prefix` string — Filters documents with the given prefix.

## Response `200`

Successful Response

- GetDocumentsResponse — Response body from GET /data/documents
  - `total_count` integer — Total number of available documents which would be returned by the request if no limit were specified. Ommitted if job_id was set in the request.
  - `next_cursor` string — Next cursor to continue pagination. Ommitted if there are no more documents after these ones, or if job_id was set in the request.
  - `documents` DocumentDescription[], required — List of documents retrieved based on the user's GET request
    - `custom_metadata` object — Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed.
    - `custom_metadata_config` object — A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits: - Maximum characters per metadata field (for prompt or rerank): **400** - Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases.
    - `id` string, uuid, required — ID of the document that was ingested
    - `name` string, required — User specified name of the document
    - `status` 'pending' | 'processing' | 'retrying' | 'completed' | 'failed' | 'cancelled', required
    - `created_at` string, required — Timestamp of when the document was created in ISO format.
    - `updated_at` string — Timestamp of when the document was modified in ISO format.
    - `ingestion_config` object — Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration.
    - `has_access` boolean — Whether the user has access to this document.

## Other responses

- `422` — Validation Error

## Changes

- **2025-10-28** `c8152db45500` — 1 breaking
  - response property `documents/items/custom_metadata/additionalProperties/` list-of-types was widened by adding types `array` to media type `application/json` of response `200`
- **2025-08-26** `db7245c74772` — 5 breaking, 4 info
  - removed the enum value `failed_to_generate_data` from the property `items/` of the `query` request parameter `ingestion_job_status`
  - removed the enum value `failed_to_provision` from the property `items/` of the `query` request parameter `ingestion_job_status`
  - removed the enum value `generating_data` from the property `items/` of the `query` request parameter `ingestion_job_status`
  - removed the enum value `provisioning` from the property `items/` of the `query` request parameter `ingestion_job_status`
  - …5 more
- **2025-05-08** `17bdb8a33fb4` — 7 info
  - api tag `/datastores/{id}/documents` added
  - api tag `/datastores` removed
  - added the enum value `failed_to_generate_data` to the property `items/` of the `query` request parameter `ingestion_job_status`
  - added the enum value `failed_to_provision` to the property `items/` of the `query` request parameter `ingestion_job_status`
  - …3 more
- …earlier changes not shown

[Full history](https://skmtc.dev/contextualai/apis/endpoints/changes/datastores/:datastore_id/documents/get.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) · [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contextualai/endpoints/revisions/ca7f807eec8b/schema)