Pagination

This page explains how the IXO Blocksync GraphQL API splits large result sets into pages, and how you move through them with cursors. Use it when a query returns more records than you want in one response.

After reading it, you can request a page of a chosen size, fetch the next or the previous page, and tell when there is no more data.

Default pagination

The IXO Blocksync GraphQL API uses a default pagination value of 10 items across all queries.

Pagination parameters

Argument	What it does
`first`	Defines the number of records to return in each query.
`last`	Defines the number of records to return, starting from the end of the dataset.
`after`	Cursor to indicate the point in the dataset from which to continue fetching results.
`before`	Cursor to navigate backward from a specific point in the dataset.

first

query {
  entities(first: 50) {
    edges {
      node {
        id
        name
      }
    }
  }
}

last

query {
  entities(last: 10) {
    edges {
      node {
        id
        name
      }
    }
  }
}

after

query {
  entities(first: 20, after: "YXJyYXljb25uZWN0aW9uOjEw") {
    edges {
      node {
        id
        name
      }
    }
  }
}

before

query {
  entities(last: 10, before: "YXJyYXljb25uZWN0aW9uOjIw") {
    edges {
      node {
        id
        name
      }
    }
  }
}

Response structure

A paginated response includes metadata for navigation:

{
  "data": {
    "entities": {
      "edges": [
        {
          "node": {
            "id": "did:ixo:entity:001",
            "name": "Entity One"
          }
        }
      ],
      "pageInfo": {
        "endCursor": "YXJyYXljb25uZWN0aW9uOjIw",
        "hasNextPage": true
      }
    }
  }
}

Response fields

Field	Meaning
`edges`	Array of results
`pageInfo.endCursor`	Reference point for next results
`pageInfo.hasNextPage`	Indicates more data availability

Best practices

Practice	What to do
Set reasonable limits	Use 20-100 items per query for optimal performance.
Handle end of data	Check `hasNextPage` to determine if more data is available.
Avoid hardcoding	Use cursor values from responses. Do not hardcode them.
Monitor rate limits	Implement rate limiting strategies to avoid 429 errors.

Where it suits your application, cache paginated results on the client.

Error handling

Error	Cause and response
400 Bad Request	Occurs with invalid cursor values. Always use cursors from previous responses.
429 Too Many Requests	Implement retry logic with exponential backoff when rate limits are reached.

IXO Blocksync GraphQL API

The endpoint, its queries and filters.

Errors

The status codes and error body IXO APIs return.