1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
---
title: "List Memories"
description: "Retrieve paginated memories with filtering and sorting options"
sidebarTitle: "Overview"
---
Retrieve paginated memories with filtering and sorting options from your Supermemory account.
## Quick Start
<Tabs>
<Tab title="TypeScript">
```typescript
import Supermemory from 'supermemory';
const client = new Supermemory({
apiKey: process.env.SUPERMEMORY_API_KEY!
});
const memories = await client.documents.list({ limit: 10 });
console.log(memories);
```
</Tab>
<Tab title="Python">
```python
from supermemory import Supermemory
import os
client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))
memories = client.documents.list(limit=10)
print(f"Found {len(memories.memories)} memories")
```
</Tab>
<Tab title="cURL">
```bash
curl -X POST "https://api.supermemory.ai/v3/documents/list" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 10}'
```
</Tab>
</Tabs>
## Response Schema
The endpoint returns a structured response containing your memories and pagination information:
```json
{
"memories": [
{
"id": "abc123",
"connectionId": null,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:35:00.000Z",
"customId": "ml-basics-001",
"title": "Introduction to Machine Learning",
"summary": "This document introduces machine learning as a subset of artificial intelligence...",
"status": "done",
"type": "text",
"metadata": {
"category": "education",
"priority": "high",
"source": "research-notes"
},
"containerTags": ["user_123", "ai-research"]
}
],
"pagination": {
"currentPage": 1,
"totalPages": 3,
"totalItems": 25,
"limit": 10
}
}
```
### Memory Object Fields
<Accordion title="Core Fields" defaultOpen>
| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier for the memory |
| `status` | ProcessingStatus | Current processing status (`queued`, `extracting`, `chunking`, `embedding`, `indexing`, `done`, `failed`) |
| `type` | MemoryType | Content type (`text`, `pdf`, `webpage`, `video`, `image`, etc.) |
| `title` | string \| null | Auto-generated or custom title |
| `summary` | string \| null | AI-generated summary of content |
| `createdAt` | string | ISO 8601 creation timestamp |
| `updatedAt` | string | ISO 8601 last update timestamp |
</Accordion>
<Accordion title="Optional Fields">
| Field | Type | Description |
|-------|------|-------------|
| `customId` | string \| null | Your custom identifier for the memory |
| `connectionId` | string \| null | ID of connector that created this memory |
| `metadata` | object \| null | Custom key-value metadata you provided |
| `containerTags` | string[] | Tags for organizing and filtering memories |
</Accordion>
## Key Parameters
All parameters are optional and sent in the request body since this endpoint uses `POST`:
<ParamField path="limit" type="number/string" default="50">
**Number of items per page.** Controls how many memories are returned in a single request. Maximum recommended: 200 for optimal performance.
</ParamField>
<ParamField path="page" type="number/string" default="1">
**Page number to fetch (1-indexed).** Use with `limit` to paginate through large result sets.
</ParamField>
<ParamField path="containerTags" type="string[]">
**Filter by tags.** Memories must match ALL provided tags. Use for filtering by user ID, project, or custom organization tags.
</ParamField>
<ParamField path="sort" type="string" default="createdAt">
**Sort field.** Options: `"createdAt"` (when memory was added) or `"updatedAt"` (when memory was last modified).
</ParamField>
<ParamField path="order" type="string" default="desc">
**Sort direction.** Use `"desc"` for newest first, `"asc"` for oldest first.
</ParamField>
<ParamField path="filters" type="string">
**Advanced filtering.** Filter based on metadata with advanced SQL logic.
</ParamField>
## Examples
<CardGroup cols={2}>
<Card title="Basic Listing" icon="list" href="/list-memories/examples/basic">
Simple memory retrieval with default settings
</Card>
<Card title="Filtering" icon="filter" href="/list-memories/examples/filtering">
Filter by tags, status, and other criteria
</Card>
<Card title="Pagination" icon="arrow-right" href="/list-memories/examples/pagination">
Handle large datasets with pagination
</Card>
<Card title="Status Monitoring" icon="chart-line" href="/list-memories/examples/monitoring">
Track processing status across memories
</Card>
</CardGroup>
<Note>
The `/v3/documents/list` endpoint uses **POST** method, not GET. This allows for complex filtering parameters in the request body.
</Note>
|