> ## Documentation Index > Fetch the complete documentation index at: https://supermemory-personal-brain-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List documents > Retrieves a paginated list of documents with their metadata and workflow status ## OpenAPI ````yaml https://api.supermemory.ai/v4/openapi post /v3/documents/list openapi: 3.1.0 info: title: supermemory API description: >- The Memory API for the AI era. OpenAPI operations include x-codeSamples for the official TypeScript and Python SDKs (Mintlify-compatible). version: 3.0.0 servers: - description: Production Server url: https://api.supermemory.ai security: - bearerAuth: [] tags: - name: Ingest description: Ingest documents, files, URLs, conversations, and other content - name: Recall (Search) description: >- Semantic recall across your content — supports memories, hybrid, and documents modes - name: Profiles description: >- Entity profiles for users, participants, or any entity — includes profile search - name: Content Management description: List, get, update, and delete content and memories - name: Container Tags description: List and manage container tags (spaces) — settings, merge, and delete - name: Connections description: External service integrations - name: Settings description: Organization settings - name: Documents description: List, get, and search documents paths: /v3/documents/list: post: tags: - Documents summary: List documents description: >- Retrieves a paginated list of documents with their metadata and workflow status operationId: postV3DocumentsList requestBody: required: true content: application/json: schema: type: object properties: containerTags: description: >- 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. deprecated: true x-hidden: true type: array items: type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ filters: $ref: '#/components/schemas/QueryFilter' description: >- Optional filters to apply to the search. Can be a JSON string or Query object. includeContent: default: false description: >- Whether to include the content field in the response. Warning: This can make responses significantly larger. example: false type: boolean limit: description: Number of items per page example: '10' anyOf: - type: string pattern: ^\d+$ - type: number order: default: desc description: Sort order example: desc type: string enum: - asc - desc page: description: Page number to fetch example: '1' anyOf: - type: string pattern: ^\d+$ - type: number sort: default: createdAt description: Field to sort by example: createdAt type: string enum: - createdAt - updatedAt filepath: description: >- Filter documents by filepath. Exact match for full paths, prefix match if ending with / x-hidden: true type: string description: Query parameters for listing documents example: filters: AND: - filterType: metadata key: group negate: false value: jira_users - filterType: numeric key: timestamp negate: false numericOperator: '>' value: '1742745777' limit: 10 order: desc page: 1 sort: createdAt responses: '200': content: application/json: schema: type: object properties: memories: type: array items: type: object properties: connectionId: anyOf: - anyOf: - type: string minLength: 22 maxLength: 22 - type: 'null' description: >- Optional ID of connection the document was created from. This is useful for identifying the source of the document. example: conn_gdrive_8f2k - type: 'null' containerTags: readOnly: true description: >- 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. deprecated: true x-hidden: true type: array items: type: string createdAt: type: string description: Creation timestamp example: '1970-01-01T00:00:00.000Z' format: datetime customId: anyOf: - type: string maxLength: 255 description: >- Optional custom ID of the document. This could be an ID from your database that will uniquely identify this document. example: doc-api-rate-limits - type: 'null' filepath: anyOf: - type: string - type: 'null' id: type: string minLength: 22 maxLength: 22 description: Unique identifier of the document. example: acxV5LHMEsG2hMSNb4umbn metadata: anyOf: - anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: {} - type: array items: {} description: >- Optional metadata for the document. This is used to store additional information about the document. You can use this to store any additional information you need about the document. Metadata can be filtered through. Keys must be strings and are case sensitive. Values can be strings, numbers, or booleans. You cannot nest objects. example: source: upload language: en - type: 'null' status: type: string enum: - unknown - queued - extracting - chunking - embedding - indexing - done - failed description: Status of the document example: done summary: anyOf: - type: string description: Summary of the document content example: >- API rate limit policy: 100 req/min free, 1000 req/min pro. - type: 'null' title: anyOf: - type: string description: Title of the document example: API Rate Limiting Policy - type: 'null' type: type: string enum: - text - pdf - tweet - google_doc - google_slide - google_sheet - image - video - audio - notion_doc - webpage - onedrive - github_markdown - granola description: Type of the document example: text updatedAt: type: string description: Last update timestamp example: '1970-01-01T00:00:00.000Z' format: datetime url: anyOf: - anyOf: - type: string - type: 'null' description: URL of the document example: https://docs.example.com/guides/rate-limits - type: 'null' content: description: >- Content of the document (only included when includeContent=true) example: This is the content of the document... type: string required: - connectionId - createdAt - customId - filepath - id - metadata - status - summary - title - type - updatedAt pagination: type: object properties: currentPage: type: number limit: default: 10 type: number maximum: 1100 totalItems: type: number totalPages: type: number required: - currentPage - totalItems - totalPages description: Pagination metadata example: currentPage: 1 limit: 10 totalItems: 100 totalPages: 10 required: - memories - pagination description: List of documents example: memories: - id: acxV5LHMEsG2hMSNb4umbn title: API Rate Limiting Policy summary: >- API rate limit policy: 100 req/min free, 1000 req/min pro. status: done type: text createdAt: '2025-04-15T09:30:00.000Z' updatedAt: '2025-04-15T09:31:00.000Z' pagination: currentPage: 1 limit: 10 totalItems: 100 totalPages: 10 description: Successfully retrieved documents '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error x-codeSamples: - lang: typescript label: TypeScript SDK source: |- import Supermemory from "supermemory"; const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY, }); const page = await client.documents.list({ containerTags: ["user_123"], limit: 20, }); for (const doc of page.memories ?? page.documents ?? []) { console.log(doc.id, doc.status); } - lang: python label: Python SDK source: |- from supermemory import Supermemory client = Supermemory() # uses SUPERMEMORY_API_KEY page = client.documents.list(container_tags=["user_123"], limit=20) print(page) - lang: bash label: cURL source: |- curl -X POST "https://api.supermemory.ai/v3/documents/list" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "containerTags": ["user_123"], "limit": 20 }' components: schemas: QueryFilter: description: >- Root query object that must contain either an AND or OR array of filter expressions anyOf: - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of OR filter expressions required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of AND filter expressions required: - AND ErrorResponse: type: object properties: error: type: string description: Error message example: Invalid request parameters details: type: string description: Additional error details example: Query must be at least 1 character long required: - error LogicalExpression: description: >- A single filter condition or a nested AND/OR expression. The API validates up to 5 levels of nesting. anyOf: - $ref: '#/components/schemas/FilterCondition' - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'OR: Array of conditions or nested expressions' required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'AND: Array of conditions or nested expressions' required: - AND FilterCondition: type: object properties: filterType: default: metadata type: string enum: - metadata - numeric - array_contains - string_contains key: type: string negate: anyOf: - type: boolean - type: string enum: - 'true' - 'false' ignoreCase: anyOf: - type: boolean - type: string enum: - 'true' - 'false' numericOperator: default: '=' type: string enum: - '>' - < - '>=' - <= - '=' value: type: string required: - key - value description: >- A single filter condition based on metadata, numeric values, array contents, or string matching securitySchemes: bearerAuth: scheme: bearer type: http ````