---
title: "POST /v1/list-documents"
method: POST
path: "/v1/list-documents"
tags: ["DocumentService"]
---

# POST /v1/list-documents

`POST /v1/list-documents`

Lists information about each document ingested into the corpus including the Document ID and metadata. This is useful for managing the lifecycle of documents and a quick way to check which documents are already in the index.

Some tips for this API:
* This operation works with the Personal API Key and OAuth 2.0 (in a JWT "Bearer Token") authentication. You can find details of how to set up and use OAuth 2.0 [here](https://docs.vectara.com/docs/deploy-and-scale/authentication/oauth-2).

## Headers

- `customer-id` integer, required
- `timeout` string

## Request body

- ListsListDocumentsRequest — Request to list documents in a corpus.
  - `corpusId` integer — The Corpus ID.
  - `numResults` integer — Maximum number of results to be returned by the server. Max is 1000. If the value is larger than 1000, it will be capped to 1000.
  - `pageKey` string, byte — Key of the specific page of the list results to return. Null/empty value means the very first page of the results is requested.
  - `metadataFilter` string — Filter on document metadata. If empty, no filtering is done. Otherwise, only documents that match all of the specified metadata will be returned. The syntax is the same as for QueryRequest.metadata.

## Response `200`

A successful response.

- ListsListDocumentsResponse — Response of listing documents in a corpus.
  - `document` ListDocumentsResponseDocumentInfo[] — The list of documents.
    - `id` string — The document ID that was used when indexing the document.
    - `metadata` ComvectaraAttribute[] — Document metadata.
      - `name` string — Name of the document metadata attribute.
      - `value` string — Value of the document metadata attribute.
  - `nextPageKey` string, byte — Represents the pagination key to retrieve the next page of results. If the value is "", it means no further results for the request. To retrieve the next page of results, client shall pass the value of next_page_key in the subsequent ListDocumentsRequest method call (in the request message's page_key field).

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api/revisions/d4c8fc1d0e7a/schema)