> ## Documentation Index > Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt > Use this file to discover all available pages before exploring further. # List 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. ## OpenAPI ````yaml api-reference/openapi.json get /datastores/{datastore_id}/documents openapi: 3.1.0 info: title: Endpoints version: '1.0' servers: - url: https://api.contextual.ai/v1 security: - BearerAuth: [] paths: /datastores/{datastore_id}/documents: get: tags: - /datastores/{id}/documents summary: List Documents description: >- 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. operationId: list_documents_datastores__datastore_id__documents_get parameters: - name: datastore_id in: path required: true schema: type: string format: uuid description: Datastore ID of the datastore to retrieve documents for title: Datastore Id description: Datastore ID of the datastore to retrieve documents for - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: Maximum number of documents to return default: 1000 title: Limit description: Maximum number of documents to return - name: cursor in: query required: false schema: type: string description: >- Cursor from the previous call to list documents, used to retrieve the next set of results title: Cursor description: >- Cursor from the previous call to list documents, used to retrieve the next set of results - name: ingestion_job_status in: query required: false schema: type: array items: $ref: '#/components/schemas/DocumentStatusEnum' description: >- Filters documents whose ingestion job status matches (one of) the provided status(es). title: Ingestion Job Status description: >- Filters documents whose ingestion job status matches (one of) the provided status(es). - name: uploaded_after in: query required: false schema: type: string format: date-time description: Filters documents uploaded at or after specified timestamp. title: Uploaded After description: Filters documents uploaded at or after specified timestamp. - name: uploaded_before in: query required: false schema: type: string format: date-time description: Filters documents uploaded at or before specified timestamp. title: Uploaded Before description: Filters documents uploaded at or before specified timestamp. - name: document_name_prefix in: query required: false schema: type: string description: Filters documents with the given prefix. title: Document Name Prefix description: Filters documents with the given prefix. - name: document_name_search in: query required: false schema: type: string description: >- Filters documents whose name contains the search term (case-insensitive substring match). title: Document Name Search description: >- Filters documents whose name contains the search term (case-insensitive substring match). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GetDocumentsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: DocumentStatusEnum: type: string enum: - pending - processing - retrying - completed - failed - cancelled title: DocumentStatusEnum GetDocumentsResponse: properties: total_count: type: integer title: Total Count description: >- 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: type: string title: Next Cursor description: >- 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: items: $ref: '#/components/schemas/DocumentDescription' type: array title: Documents description: List of documents retrieved based on the user's GET request type: object required: - documents title: GetDocumentsResponse description: Response body from GET /data/documents HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DocumentDescription: properties: custom_metadata: additionalProperties: anyOf: - type: boolean - type: number - type: integer - type: string - items: type: number type: array type: object title: Custom Metadata description: >- 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: additionalProperties: $ref: '#/components/schemas/MetadataFieldConfig' type: object title: Custom Metadata Config description: >- 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: type: string format: uuid title: Id description: ID of the document that was ingested name: type: string title: Name description: User specified name of the document status: $ref: '#/components/schemas/DocumentStatusEnum' description: Status of this document's ingestion job created_at: type: string title: Created At description: Timestamp of when the document was created in ISO format. updated_at: type: string title: Updated At description: Timestamp of when the document was modified in ISO format. ingestion_config: title: Ingestion Config description: >- Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration. has_access: type: boolean title: Has Access description: Whether the user has access to this document. default: true type: object required: - id - name - status - created_at title: DocumentDescription description: Document description ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MetadataFieldConfig: properties: in_chunks: type: boolean title: In Chunks description: >- Whether to add in chunks. Defaults to True. The maximum amount of characters per metadata field that can be added to the prompt or rerank is 400. The maximum amount of metadata fields that can be added for prompt or retrieval is 10. Contact support@contextual.ai to request quota increases. default: true returned_in_response: type: boolean title: Returned In Response description: Whether to add in response. Defaults to False default: false filterable: type: boolean title: Filterable description: Whether to use in filtering. Defaults to True default: true type: object title: MetadataFieldConfig securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````