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 (legacy)

The traditional way to paginate using offset and limit parameters:

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

This method works well for small datasets but becomes inefficient for large offsets, as the database still needs to scan through all the skipped rows.

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:

PropertyTypeDescription
limitNumberThe number of items per page (as requested)
hasNextPageBooleanWhether there are more results available after the current page
hasPreviousPageBooleanWhether there are results available before the current page
nextCursorString/nullThe cursor to use for the next page, or null if there are no more results
previousCursorString/nullThe 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

ErrorDescription
INVALID_CURSORThe cursor string is malformed or could not be decoded. Start pagination from the beginning without a cursor.
CURSOR_MISMATCHThe 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_CONFLICTBoth cursor and offset parameters were provided. Use only one pagination method per request.

Supported endpoints

Cursor-based pagination is available on the following endpoints:

Coins:

Exchanges:

Markets:

Tags:

Other:

Previous

Find UUIDs

 Next

Introduction

On this page