---
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` JobStatusEnum[] — 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.

## 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
    - `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.

## Other responses

- `422` — Validation Error

## Changes

- **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
- **2025-02-26** `5298551c424b` — 6 warning, 3 info
  - added the new `cancelled` enum value to the `documents/items/status` response property for the response status `200`
  - added the new `completed` enum value to the `documents/items/status` response property for the response status `200`
  - added the new `failed` enum value to the `documents/items/status` response property for the response status `200`
  - added the new `pending` enum value to the `documents/items/status` response property for the response status `200`
  - …5 more
- **2025-01-14** `a02ba25a1da1` — 1 warning, 1 info
  - deleted the `query` request parameter `ingestion_job_status[]`
  - added the new optional `query` request parameter `ingestion_job_status`
- **2025-01-14** `34bdb8a45e5c` — 1 warning, 1 info
  - deleted the `query` request parameter `ingestion_job_status`
  - added the new optional `query` request parameter `ingestion_job_status[]`

[Change 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/17bdb8a33fb4/schema)