Documentation / Guides

Pagination

Two ways to page GreyhoundAPI list endpoints: simple 1-based page numbers, or opaque cursors for large and streaming exports.

Every list endpoint can be paged two ways. They work on the same endpoints, so pick whichever suits the job — and you can switch between them mid-stream.

Page numbers

The simplest option: ask for a page with page (1-based). The response tells you exactly where you are and how many pages there are.

curl "https://api.greyhoundapi.com/v1/results?date_from=2026-07-01&page=2&limit=100" \
  -H "X-API-Key: $GAPI_KEY"
{
  "meta": {
    "count": 100,
    "next_cursor": "eyJzIjoi...",
    "page": 2,
    "per_page": 100,
    "total": 4980,
    "total_pages": 50,
    "next_page": 3,
    "prev_page": 1
  },
  "data": [ ... ]
}

Page numbers are ideal for UI pagers and for browsing bounded (date-filtered) result sets. They are less suited to very large exports: deep pages get progressively slower, and a page can shift if new races land while you iterate. For those, use cursors.

You don't have to ask for page 1 explicitly: the first response of a paged list (a call with no cursor) already carries page, per_page, total, total_pages and next_page — so you learn the size of the result set from the first request. A cursor continuation stays lean, returning just count and next_cursor.

Cursors

Cursors page by sort position rather than offset, so results stay stable even while new races arrive underneath the query, and page 10,000 is as fast as page 1. Follow meta.next_cursor until it is absent.

curl "https://api.greyhoundapi.com/v1/results?date_from=2026-07-01&limit=100" \
  -H "X-API-Key: $GAPI_KEY"
# -> meta.next_cursor: "eyJzIjoi..."

curl "https://api.greyhoundapi.com/v1/results?date_from=2026-07-01&limit=100&cursor=eyJzIjoi..." \
  -H "X-API-Key: $GAPI_KEY"

Cursors are opaque — pass meta.next_cursor back unchanged and do not build or parse them yourself. When it is absent, you have reached the last page.

Which should I use?

Use caseReach for
UI pagers, jumping to a specific page, small or date-bounded queriespage
Bulk exports (e.g. ML training sets), full-archive pulls, catch-up after a disconnectcursor

You are not locked in: a page-number response also carries a next_cursor, so you can start on page=1 and switch to cursors once past the first page. If you pass both, page takes precedence.

Page size

limit accepts 1–200 and defaults to 50. It applies to both styles.