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

# List memories

> GET /v1/memories — list memories with optional filters and cursor-based pagination.

## `GET /v1/memories`

List memories for your organization with optional filtering by agent and user. Results are paginated using opaque cursors. Content is excluded from results — use `GET /v1/memories/{id}` to fetch the full record.

**Required scope:** `memory:read`

***

## Request

```bash theme={null}
curl "https://api.thrindex.com/v1/memories?agent_id=support-agent&user_id=user-42&limit=50" \
  -H "Authorization: Bearer th_live_..."
```

### Query parameters

| Parameter  | Type    | Required | Default | Description                                                                                                       |
| ---------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `agent_id` | string  | no       | —       | Filter to memories belonging to this agent. Must match `[A-Za-z0-9._:-]`, max 256 chars. Omit to list all agents. |
| `user_id`  | string  | no       | —       | Filter to memories belonging to this user. Same constraints. Omit to list all users.                              |
| `limit`    | integer | no       | `50`    | Results per page. Range: `1`–`200`. Values outside range are clamped.                                             |
| `cursor`   | string  | no       | —       | Opaque cursor from `next_cursor` of a previous response. Omit for the first page.                                 |

***

## Response

### `200 OK`

```json theme={null}
{
  "results": [
    {
      "id": "3f2e1d0c-1234-5678-abcd-ef0123456789",
      "org_id": "org_abc...",
      "agent_id": "support-agent",
      "user_id": "user-42",
      "level": 0,
      "status": "active",
      "importance": 0.82,
      "confidence": 1.0,
      "source": "agent",
      "created_at": "2026-05-24T17:00:00.000Z",
      "updated_at": "2026-05-24T17:00:00.000Z"
    }
  ],
  "next_cursor": "eyJpZCI6Ii4..."
}
```

### Top-level fields

| Field         | Type              | Description                                                                                       |
| ------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `results`     | array             | Current page of memory records.                                                                   |
| `next_cursor` | string \| omitted | Opaque pagination cursor. Pass as `cursor` in the next request. Absent when no more pages remain. |

### Memory record fields

| Field        | Type            | Description                           |
| ------------ | --------------- | ------------------------------------- |
| `id`         | string (UUID)   | Memory identifier                     |
| `org_id`     | string          | Your organization identifier          |
| `agent_id`   | string          | Agent that owns the memory            |
| `user_id`    | string          | User the memory belongs to            |
| `level`      | integer         | `0` = raw, `1` = abstraction          |
| `status`     | string          | `"active"` or `"deprecated"`          |
| `importance` | float (0–1)     | Importance score                      |
| `confidence` | float (0–1)     | Confidence score                      |
| `source`     | string          | Origin of the memory (e.g. `"agent"`) |
| `created_at` | ISO 8601 string | Creation timestamp                    |
| `updated_at` | ISO 8601 string | Last update timestamp                 |

<Note>
  `content` is intentionally omitted from list results to keep paginated payloads small. Use `GET /v1/memories/{id}` to retrieve the full record including content.
</Note>

***

## Pagination

Iterate through all pages by following `next_cursor` until it is absent:

```bash theme={null}
# First page
curl "https://api.thrindex.com/v1/memories?agent_id=support-agent&limit=100" \
  -H "Authorization: Bearer th_live_..."

# Next page (use next_cursor from the previous response)
curl "https://api.thrindex.com/v1/memories?agent_id=support-agent&limit=100&cursor=eyJpZCI6Ii4..." \
  -H "Authorization: Bearer th_live_..."
```

***

## Examples

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from thrindex import Thrindex, ListResponse

    client = Thrindex(api_key="th_live_...")

    # Fetch the first page
    page: ListResponse = client.list(
        agent_id="support-agent",
        user_id="user-42",
        limit=50,
    )

    # Iterate through all pages
    all_memories = []
    while True:
        all_memories.extend(page.results)
        if not page.next_cursor:
            break
        page = client.list(
            agent_id="support-agent",
            user_id="user-42",
            cursor=page.next_cursor,
        )

    print(f"Total memories: {len(all_memories)}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { ThrindexClient } from 'thrindex';
    import type { ListResponse, MemoryRecord } from 'thrindex';

    const client = new ThrindexClient({ apiKey: 'th_live_...' });

    // Iterate through all pages
    const allMemories: MemoryRecord[] = [];
    let page: ListResponse = await client.list({
      agentId: 'support-agent',
      userId: 'user-42',
      limit: 50,
    });

    while (true) {
      allMemories.push(...page.results);
      if (!page.nextCursor) break;
      page = await client.list({
        agentId: 'support-agent',
        userId: 'user-42',
        cursor: page.nextCursor,
      });
    }

    console.log(`Total memories: ${allMemories.length}`);
    ```
  </Tab>
</Tabs>

***

## Errors

| Status | Code               | Description                             |
| ------ | ------------------ | --------------------------------------- |
| `400`  | `validation_error` | Invalid `agent_id` or `user_id` charset |
| `401`  | `unauthorized`     | Missing or invalid API key              |
| `401`  | `forbidden`        | API key lacks `memory:read` scope       |
| `429`  | `rate_limited`     | Rate limit exceeded                     |
| `500`  | `internal_error`   | Server error                            |