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. 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:

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

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.

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:

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 -

HTTP/1.1 200 OK
X-Next-Cursor: eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMVQxMjowMDowMCIsImlkIjoxMjM0NX0

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

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:

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

API Basics

Samples

Projects

Metadata & Tags

Analyses

Jobs

Documents

Webhooks & Events

Users & Account

Sequencing

Example

​Page-based pagination

​Cursor-based pagination

​Example

Page-based pagination

Cursor-based pagination

Example