---
title: "List documents"
method: POST
path: "/v3/documents/list"
tags: ["Documents"]
---

# List documents

`POST /v3/documents/list`

Retrieves a paginated list of documents with their metadata and workflow status

## Request body

- object — Query parameters for listing documents
  - `containerTags` string[] — Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents.
  - `filters` union — Optional filters to apply to the search. Can be a JSON string or Query object.
    - object
      - `OR` union[], required — Array of OR filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
    - object
      - `AND` union[], required — Array of AND filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
  - `includeContent` boolean — Whether to include the content field in the response. Warning: This can make responses significantly larger.
  - `limit` union — Number of items per page
    - string
    - number
  - `order` 'asc' | 'desc' — Sort order
  - `page` union — Page number to fetch
    - string
    - number
  - `sort` 'createdAt' | 'updatedAt' — Field to sort by
  - `filepath` string — Filter documents by filepath. Exact match for full paths, prefix match if ending with /

## Response `200`

Successfully retrieved documents

- object — List of documents
  - `memories` object[], required
    - `connectionId` string, nullable, required
    - `containerTags` string[] — Optional tags this document should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to group documents.
    - `createdAt` string, datetime, required — Creation timestamp
    - `customId` string, nullable, required — Optional custom ID of the document. This could be an ID from your database that will uniquely identify this document.
    - `filepath` string, nullable, required
    - `id` string, required — Unique identifier of the document.
    - `metadata` union, required
      - string
      - number
      - boolean
      - object
      - unknown[]
        - unknown
    - `status` 'unknown' | 'queued' | 'extracting' | 'chunking' | 'embedding' | 'indexing' | 'done' | 'failed', required — Status of the document
    - `summary` string, nullable, required — Summary of the document content
    - `title` string, nullable, required — Title of the document
    - `type` 'text' | 'pdf' | 'tweet' | 'google_doc' | 'google_slide' | 'google_sheet' | 'image' | 'video' | 'audio' | 'notion_doc' | 'webpage' | 'onedrive' | 'github_markdown', required — Type of the document
    - `updatedAt` string, datetime, required — Last update timestamp
    - `url` string, nullable
    - `content` string — Content of the document (only included when includeContent=true)
  - `pagination` object, required — Pagination metadata
    - `currentPage` number, required
    - `limit` number
    - `totalItems` number, required
    - `totalPages` number, required

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `500` — Internal server error

## Changes

- **2026-04-21** `0240419cabee` — 1 info
  - added the optional property `memories/items/url` to the response with the `200` status
- **2026-04-17** `f09b91ede978` — 2 info
  - added the new optional request property `filepath`
  - added the required property `memories/items/filepath` to the response with the `200` status
- **2026-04-06** `cb825424a780` — 2 info
  - api tag `Documents` added
  - api tag `Manage Documents` removed
- **2026-03-15** `b40318167017` — 1 breaking
  - request body became required
- **2026-03-12** `7386f0fb8043` — 1 warning
  - changed the pattern of the request property `containerTags/items/` from `^[a-zA-Z0-9_-]+$` to `^[a-zA-Z0-9_:-]+$`

[Full history](https://skmtc.dev/supermemoryai/apis/supermemory-api/changes/v3/documents/list/post.md)

---

[API](https://skmtc.dev/supermemoryai/apis/supermemory-api.md) · [All operations](https://skmtc.dev/supermemoryai/apis/supermemory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/supermemoryai/supermemory-api/revisions/f979eba02e97/schema)