# List and retrieve documents
Source: https://nordvec.com/docs/guides/how-to/list-documents

Page through your documents with cursor pagination, filter and sort them, and fetch one or many by id.

Where [search](/docs/guides/how-to/filter-search) ranks documents by relevance to
a query, listing walks your whole corpus in order. Use it to sync, audit, or
build your own index over what Nordvec holds. Listing returns metadata only, no
document content.

## List with cursor pagination [#list-with-cursor-pagination]

`/documents/list` returns a page of documents plus an opaque `nextCursor`. Pass
that cursor back to get the next page, and stop when `hasMore` is `false`.

```bash
curl "https://nordvec.com/api/v1/documents/list?limit=50" \
  -H "Authorization: Bearer $NORDVEC_API_KEY"
```

```json
{
  "items": [
    { "id": "…", "title": "Q3 Financial Report", "status": "indexed", "datasource": "finance", "created_at": "2026-04-01T10:00:00Z" }
  ],
  "nextCursor": "eyJrIjoi…",
  "hasMore": true
}
```

Signed in, you can list the first page of your own documents from here:

Try it in the API reference: [`GET /api/v1/documents/list`](https://nordvec.com/docs/api#tag/documents/GET/documents/list) (List documents).

To walk every page, loop until `hasMore` is `false`, passing the previous
response's `nextCursor` each time, with the same `sort` and `direction`:

```bash
curl "https://nordvec.com/api/v1/documents/list?limit=50&cursor=eyJrIjoi…" \
  -H "Authorization: Bearer $NORDVEC_API_KEY"
```

<Callout>
The cursor is opaque, do not parse or construct it. Pass back exactly what the
previous response returned. An invalid cursor, or one from a different sort
order, is rejected.
</Callout>

## Filter and sort [#filter-and-sort]

All filters are optional and combine with AND. Sorting defaults to newest first.

| Field | Type | Notes |
|---|---|---|
| `limit` | integer | 1 to 200 (default 50). |
| `cursor` | string | Opaque cursor from the previous page. |
| `datasource` | string | Restrict to one datasource by its slug (up to 200 characters). |
| `status` | enum | `indexed`, `processing`, or `failed`. |
| `sourceProvider` | string | Restrict to one connector provider, for example `google` or `slack`. |
| `contentType` | string | Restrict to one knowledge type, for example `policy` or `runbook`. |
| `createdAfter` / `createdBefore` | string | ISO 8601 timestamps with an offset, both inclusive. |
| `sort` | enum | `createdAt` (default), `updatedAt`, or `title`. |
| `direction` | enum | `desc` (default) or `asc`. |

```bash
curl "https://nordvec.com/api/v1/documents/list?status=indexed&datasource=finance&sort=updatedAt&direction=desc&limit=100" \
  -H "Authorization: Bearer $NORDVEC_API_KEY"
```

### Which sort to walk with [#which-sort-to-walk-with]

- **A complete, one-shot enumeration**: `sort=createdAt`. The creation time
  never changes, so every document appears exactly once.
- **Incremental catch-up from a watermark**: `sort=updatedAt&direction=asc`. A
  document updated while you walk can appear twice, so upsert by `id`.
- **Display order**: `updatedAt` or `title` descending. A document updated
  between two pages can move past the cursor and be skipped, so do not use it
  to enumerate.

## Fetch a single document [#fetch-a-single-document]

`/documents/{id}` returns one document's metadata, processing state and text.
A long text can be read in windows: `contentOffset` and `contentMaxChars`
(counted in UTF-16 code units) select one window, and `content_range` reports
the window and the full length, so keep reading until `offset + length` reaches
`total`.

```bash
curl "https://nordvec.com/api/v1/documents/DOCUMENT_ID?contentMaxChars=100000" \
  -H "Authorization: Bearer $NORDVEC_API_KEY"
```

## Fetch many at once [#fetch-many-at-once]

To resolve up to 200 ids in one call, POST them to `/documents/batch` instead of
making one request per id. The batch returns metadata and processing state;
`content` is always `null`, so read the text with the single-document call.

```bash
curl https://nordvec.com/api/v1/documents/batch \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["DOCUMENT_ID_1", "DOCUMENT_ID_2"] }'
```

<Callout>
Listing, like search, only ever returns documents the caller is allowed to see.
`status` tells you where a document is in processing: `processing` while it is
still being indexed, `failed` when it could not be. See
[Documents & search](/docs/guides/concepts/documents) for the lifecycle.
</Callout>

## Next steps [#next-steps]

<Cards>
  <Card title="Filter and refine search" href="/docs/guides/how-to/filter-search" />
  <Card title="Documents & search" href="/docs/guides/concepts/documents" />
  <Card title="API reference" href="/docs/api" />
</Cards>