---
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 — Root query object that must contain either an AND or OR array of filter expressions
    - object
      - `OR` LogicalExpression[], required — Array of OR filter expressions
        - union — A single filter condition or a nested AND/OR expression. The API validates up to 5 levels of nesting.
          - FilterCondition — 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` LogicalExpression[], required — OR: Array of conditions or nested expressions
          - object
            - `AND` LogicalExpression[], required — AND: Array of conditions or nested expressions
    - object
      - `AND` LogicalExpression[], required — Array of AND filter expressions
        - union — A single filter condition or a nested AND/OR expression. The API validates up to 5 levels of nesting.
          - FilterCondition — 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` LogicalExpression[], required — OR: Array of conditions or nested expressions
          - object
            - `AND` LogicalExpression[], 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' | 'granola', 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

---

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