The API uses cursor-based pagination to efficiently traverse large datasets. This approach is more reliable than offset-based pagination when data may change between requests.

How it works

1. Include an optional limit parameter in the request (default: 100, max: 1000)
2. Inspect the pagination object in the response
3. If has_more is true, pass the cursor value to retrieve the next page

Example

Initial request:

curl -H "x-api-key: sk_live_your_key" \
  "https://portal.h2gc.com/api/v1/financials?metric=ggr_annual&country=United+Kingdom&limit=50"

Response:

{
  "meta": {
    "dataset": "ggr_annual",
    "metric": "ggr_annual",
    "granularity": "annual",
    "filters_applied": { "country": ["United Kingdom"] },
    "row_count": 50
  },
  "data": ["...50 rows..."],
  "pagination": {
    "cursor": "eyJvIjo1MH0",
    "has_more": true
  }
}

Subsequent request — include the same filters along with the cursor:

curl -H "x-api-key: sk_live_your_key" \
  "https://portal.h2gc.com/api/v1/financials?metric=ggr_annual&country=United+Kingdom&limit=50&cursor=eyJvIjo1MH0"

Pagination fields

Best practices

• Do not decode cursors — cursors should be treated as opaque strings. The internal format may change without notice.
• Maintain consistent parameters — the same query filters should be used when paginating. Changing filters mid-pagination produces undefined results.
• Respect limits — the maximum limit is 1000 rows per request.