Pagination

Most endpoints that return lists of items support pagination. You can use pagination to retrieve results in smaller chunks, which is especially useful when working with large datasets.

Pagination methods

The Coinranking API supports two pagination methods:

1. Offset-based pagination (deprecated)

The traditional way to paginate using offset and limit parameters:

...coins?limit=50&offset=100

This method is deprecated and will be removed in a future version. The maximum supported offset is 5000; requests with a larger offset return an OFFSET_TOO_LARGE error. To retrieve results beyond that, use cursor-based pagination instead.

Cursor-based pagination uses an opaque cursor string to mark your position in the result set:

...coins?limit=50&cursor=eyJ0IjoxLCJyIjoxMjM0NTY3ODkwLC...

This method is more efficient and provides consistent results even when data changes between requests.

How cursor pagination works

  1. First request: Make a request without a cursor to get the first page of results
  2. Get the cursor: The response includes a pagination object with a nextCursor value
  3. Next request: Use the nextCursor value as the cursor parameter for the next page
  4. Repeat: Continue until hasNextPage is false or nextCursor is null

You can also navigate backward through results using the previousCursor:

  1. Check availability: The response includes hasPreviousPage and previousCursor fields
  2. Go back: Use the previousCursor value as the cursor parameter to return to the previous page
  3. Repeat: Continue until hasPreviousPage is false or previousCursor is null

Example flow

First request:

GET /v2/coins?limit=10

Response:

json 
{
  "status": "success",
  "data": {
    "coins": [...]
  },
  "pagination": {
    "limit": 10,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "eyJ0IjoxLCJyIjoxMjM0NTY3ODkwLC...",
    "previousCursor": null
  }
}

Second request (forward):

GET /v2/coins?limit=10&cursor=eyJ0IjoxLCJyIjoxMjM0NTY3ODkwLC...

Response:

json 
{
  "status": "success",
  "data": {
    "coins": [...]
  },
  "pagination": {
    "limit": 10,
    "hasNextPage": true,
    "hasPreviousPage": true,
    "nextCursor": "eyJ0IjoyLCJyIjo5ODc2NTQzMjEwLC...",
    "previousCursor": "eyJ0IjoxLCJyIjoxMjM0NTY3ODkwLC..."
  }
}

Go back (backward):

GET /v2/coins?limit=10&cursor=eyJ0IjoxLCJyIjoxMjM0NTY3ODkwLC...

This returns you to the previous page of results.

Pagination response object

All paginated endpoints return a pagination object in their response:

Property Type Description
limit Number The number of items per page (as requested)
hasNextPage Boolean Whether there are more results available after the current page
hasPreviousPage Boolean Whether there are results available before the current page
nextCursor String/null The cursor to use for the next page, or null if there are no more results
previousCursor String/null The cursor to use for the previous page, or null if on the first page

Important notes

Cursor consistency: The cursor is tied to the orderBy and orderDirection parameters used in the original request. If you change these parameters, you must start pagination from the beginning without a cursor.
No mixing: You cannot use cursor and offset parameters together. If both are provided, you will receive a PAGINATION_CONFLICT error.
Cursor expiration: Cursors do not expire, but they may become invalid if the underlying data structure changes significantly. In such cases, start pagination from the beginning.

Error responses

Error Description
INVALID_CURSOR The cursor string is malformed or could not be decoded. Start pagination from the beginning without a cursor.
CURSOR_MISMATCH The cursor was created with different orderBy or orderDirection parameters than the current request. Either match the original parameters or start pagination from the beginning.
PAGINATION_CONFLICT Both cursor and offset parameters were provided. Use only one pagination method per request.
OFFSET_TOO_LARGE The offset exceeds the maximum of 5000. Offset-based pagination is deprecated; use cursor-based pagination for deeper results.

Supported endpoints

Cursor-based pagination is available on the following endpoints:

Coins:

Exchanges:

DEXs:

Futures:

Markets:

Tags:

Assets:

Other:

Previous

Find UUIDs

 Next

Errors