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

# Pagination

List endpoints return results one page at a time. The One Codex API supports two pagination styles:

* **Page-based** (default): request pages by number. Supported by all list endpoints.
* **Cursor-based**: follow a cursor from one page to the next. Supported by `/api/v1/samples`, `/api/v1/samples/public`, and `/api/v1/metadata`. Recommended when fetching large numbers of samples or metadata records.

## Page-based pagination

Page-based pagination follows the basic model of the [GitHub API](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api). Pages may be requested using the `page` and `per_page` query string arguments:

| Parameter | Default | Description |
| - | - | - |
| `page` | `1` | The page number to return, starting at 1 |
| `per_page` | `20` | The number of results per page (max 500) |

The `Link` header lists links to the current (`self`), `next`, and `last` pages. The `X-Total-Count` header contains a count of the total number of items:

```text text theme={null}
HTTP/1.1 200 OK
Link: </api/v1/samples?page=1&per_page=20>; rel="self",
      </api/v1/samples?page=2&per_page=20>; rel="next",
      </api/v1/samples?page=3&per_page=20>; rel="last"
X-Total-Count: 46
```

> [!NOTE]
>
> The `next` link is included on every page, including the last one. Use the `last` link or `X-Total-Count` to tell when you have reached the end.

## Cursor-based pagination

To use cursor-based pagination, send the `X-Pagination-Style: cursor` request header. Pages are then requested using the `cursor` and `per_page` query string arguments:

| Parameter | Default | Description |
| - | - | - |
| `cursor` | (none) | The `X-Next-Cursor` value from the previous response. Omit it for the first page |
| `per_page` | `20` | The number of results per page (max 100) |

Each response includes an `X-Next-Cursor` header if more results are available. Pass its value as `cursor` to fetch the next page. The last page has no `X-Next-Cursor` header. Cursor-based responses do not include the `Link` or `X-Total-Count` headers.

> [!NOTE]
>
> The `page` and `cursor` arguments cannot be combined. Sending `page` with the `X-Pagination-Style: cursor` header, or `cursor` without it, returns a `400 Bad Request`.

A cursor is tied to the sort order of the request that produced it. Keep the same `sort` and `where` arguments for every page.

### Example

Fetch the first page of samples, most recent first:

```shell curl theme={null}
curl --get https://app.onecodex.com/api/v1/samples \
  -H "X-API-Key: $ONE_CODEX_API_KEY" \
  -H "X-Pagination-Style: cursor" \
  --data-urlencode 'sort={"created_at": true}' \
  --data-urlencode "per_page=100" \
  -D -
```

```text text theme={null}
HTTP/1.1 200 OK
X-Next-Cursor: eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMVQxMjowMDowMCIsImlkIjoxMjM0NX0
```

Then pass the cursor to fetch the next page, keeping the same `sort`:

```shell curl theme={null}
curl --get https://app.onecodex.com/api/v1/samples \
  -H "X-API-Key: $ONE_CODEX_API_KEY" \
  -H "X-Pagination-Style: cursor" \
  --data-urlencode 'sort={"created_at": true}' \
  --data-urlencode "per_page=100" \
  --data-urlencode "cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMVQxMjowMDowMCIsImlkIjoxMjM0NX0" \
  -D -
```

To fetch all samples, repeat until a response has no `X-Next-Cursor` header:

```python python theme={null}
import os

import requests

url = "https://app.onecodex.com/api/v1/samples"
headers = {
    "X-API-Key": os.environ["ONE_CODEX_API_KEY"],
    "X-Pagination-Style": "cursor",
}
params = {"sort": '{"created_at": true}', "per_page": 100}

samples = []
while True:
    resp = requests.get(url, headers=headers, params=params)
    resp.raise_for_status()
    samples.extend(resp.json())

    next_cursor = resp.headers.get("X-Next-Cursor")
    if not next_cursor:
        break
    params["cursor"] = next_cursor
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.