> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List documents

> List documents in a namespace.

Returns up to 100 documents per page by default, in sorted order (bitwise "C" collation). Use the optional `prefix` parameter to limit results to documents whose IDs start with a given prefix. When there are more documents to return, the response includes a `pagination` token you can pass to retrieve the next page. When no `pagination` token is returned, there are no more documents to list.

<RequestExample>
  ```python Python theme={null}
  # pip install --upgrade pinecone
  import os
  from pinecone import Pinecone

  pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
  index = pc.Index(name="articles")

  NAMESPACE = "example-namespace"

  # List every document ID in the namespace.
  # The SDK returns a paginator, so iterating it walks every page.
  for document in index.documents.list(namespace=NAMESPACE):
      print(document._id)

  # List only the IDs beginning with a prefix.
  for document in index.documents.list(namespace=NAMESPACE, prefix="report-2026#"):
      print(document._id)
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"

  # EXAMPLE REQUEST 1: List the first page of document IDs
  curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "limit": 20
    }'

  # EXAMPLE REQUEST 2: List only the IDs beginning with a prefix
  curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "prefix": "report-2026#"
    }'

  # EXAMPLE REQUEST 3: Retrieve the next page
  curl "https://$INDEX_HOST/namespaces/__default__/documents/list" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "pagination_token": "Tm90aGluZyB0byBzZWUgaGVyZQo="
    }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/list
openapi: 3.0.3
info:
  title: Pinecone Data Plane API
  description: >-
    Pinecone is a vector database that makes it easy to search and retrieve
    billions of high-dimensional vectors.
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 2026-07
servers:
  - url: https://{index_host}
    variables:
      index_host:
        default: unknown
        description: host of the index
security:
  - ApiKeyAuth: []
tags:
  - name: Vector Operations
  - name: Bulk Operations
  - name: Namespace Operations
  - name: Document Operations
    description: >-
      Operations on documents in an index created with a document schema — one
      that declares at least one full-text-searchable string field or a
      `dense_vector` / `sparse_vector` field under a name other than the
      reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
      document schema. Indexes served by the vectors API — created from
      `dimension`/`metric` on an earlier API version, or from a schema holding
      only the reserved vector fields and metadata — and indexes served by the
      records API — created with an integrated embedding model, whose schema
      holds a single `semantic_text` field — reject every document operation
      with `400` and name the API to use instead. A document index accepts only
      the document operations; the vector data operations (upsert, query, fetch,
      update, delete, list) reject it, while index stats and the namespace
      operations remain available.
externalDocs:
  description: More Pinecone.io API docs
  url: https://docs.pinecone.io/introduction
paths:
  /namespaces/{namespace}/documents/list:
    post:
      tags:
        - Document Operations
      summary: List documents
      description: >-
        List documents in a namespace.


        Returns up to 100 documents per page by default, in sorted order
        (bitwise "C" collation). Use the optional `prefix` parameter to limit
        results to documents whose IDs start with a given prefix. When there are
        more documents to return, the response includes a `pagination` token you
        can pass to retrieve the next page. When no `pagination` token is
        returned, there are no more documents to list.
      operationId: listDocuments
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            type: string
          style: simple
        - in: path
          name: namespace
          description: The namespace to list documents from.
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListDocumentsRequest'
        required: true
      responses:
        '200':
          description: A successful list response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDocumentsResponse'
              examples:
                mid_page:
                  summary: A page with more results to follow
                  value:
                    documents:
                      - _id: doc-1
                      - _id: doc-2
                    namespace: my-namespace
                    pagination:
                      next: Tm90aGluZyB0byBzZWUgaGVyZQo=
                    usage:
                      read_units: 1
                last_page:
                  summary: The final page with no further results
                  value:
                    documents:
                      - _id: doc-3
                    namespace: my-namespace
                    usage:
                      read_units: 1
          links:
            FetchListedDocument:
              description: Look up a document returned by list.
              operationId: fetchDocuments
              parameters:
                namespace: $request.path.namespace
            ListDocumentsNextPage:
              description: Fetch the next page of documents.
              operationId: listDocuments
              parameters:
                namespace: $request.path.namespace
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. Possible causes: missing or invalid API key.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedMessage'
        4XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListDocumentsRequest:
      example:
        limit: 20
        prefix: doc-
      description: The request for the `list_documents` operation.
      type: object
      properties:
        prefix:
          description: >-
            A prefix to filter document IDs. Only documents whose IDs begin with
            this prefix are returned.
          type: string
          pattern: ^[\x01-\x7F]*$
          maxLength: 512
        limit:
          description: The maximum number of documents to return per page. Defaults to 100.
          default: 100
          type: integer
          format: int32
          minimum: 1
          maximum: 100
        pagination_token:
          description: >-
            A pagination token from a previous list response, used to retrieve
            the next page of results.
          type: string
    ListDocumentsResponse:
      description: The response for the `list_documents` operation.
      type: object
      properties:
        documents:
          description: The listed documents, in sorted order by ID.
          type: array
          items:
            $ref: '#/components/schemas/ListedDocumentRecord'
        pagination:
          $ref: '#/components/schemas/Pagination'
        namespace:
          example: my-namespace
          description: The namespace the documents were listed from.
          type: string
        usage:
          $ref: '#/components/schemas/DocumentListUsage'
      required:
        - documents
        - namespace
        - usage
    ErrorResponse:
      example:
        error:
          code: INVALID_ARGUMENT
          message: >-
            No 'ids' or 'filter' provided in the document fetch request. Provide
            at least one document ID in 'ids', or a metadata filter in 'filter'.
        status: 400
      description: >-
        The error response shape returned by the records and documents
        operations. The vector operations return `rpcStatus` instead. Requests
        rejected by the authentication and rate-limiting layer before they reach
        the service (`401`, and the `400`, `403`, and `429` it produces) return
        a plain-text body on every operation.
      type: object
      properties:
        status:
          example: 400
          description: The HTTP status code of the error.
          type: integer
        error:
          description: Detailed information about the error that occurred.
          type: object
          properties:
            code:
              example: INVALID_ARGUMENT
              description: >-
                The error code.

                Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
                `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
                `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
                `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
                `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
                `PAYLOAD_TOO_LARGE`.
              x-enum:
                - OK
                - UNKNOWN
                - INVALID_ARGUMENT
                - DEADLINE_EXCEEDED
                - NOT_FOUND
                - ALREADY_EXISTS
                - PERMISSION_DENIED
                - UNAUTHENTICATED
                - RESOURCE_EXHAUSTED
                - FAILED_PRECONDITION
                - ABORTED
                - OUT_OF_RANGE
                - INTERNAL
                - FORBIDDEN
                - PAYMENT_REQUIRED
                - SERVICE_UNAVAILABLE
                - PAYLOAD_TOO_LARGE
              type: string
            message:
              example: >-
                No 'ids' or 'filter' provided in the document fetch request.
                Provide at least one document ID in 'ids', or a metadata filter
                in 'filter'.
              description: >-
                A human-readable description of the error, including how to
                correct the request where possible.
              type: string
          required:
            - code
            - message
      required:
        - status
        - error
    UnauthorizedMessage:
      example: Unauthorized
      description: >-
        The plain-text body of a `401` response. Authentication failures are
        rejected before the request reaches the index, so they carry the message
        `Unauthorized` rather than an error object.
      type: string
    ListedDocumentRecord:
      example:
        _id: doc-1
      description: A listed document containing only its ID.
      type: object
      properties:
        _id:
          description: The unique identifier of the document.
          type: string
          minLength: 1
      required:
        - _id
    Pagination:
      type: object
      properties:
        next:
          example: Tm90aGluZyB0byBzZWUgaGVyZQo=
          type: string
      required:
        - next
    DocumentListUsage:
      example:
        read_units: 1
      description: Usage information for the `list_documents` operation.
      type: object
      properties:
        read_units:
          example: 1
          description: The number of read units consumed by this operation.
          type: integer
          format: int32
      required:
        - read_units
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: >-
        An API Key is required to call Pinecone APIs. Get yours from the
        [console](https://app.pinecone.io/).

````