# Pagination

GraphQL queries in Umbraco Compose support two different pagination approaches depending on the type of data being paginated:

* **Cursor-based pagination** for references (connections)
* **Index-based pagination** for nested/embedded arrays

{% hint style="info" %}
The page size is limited to a maximum of 100 items per page. If you request more than 100 items, the API will return an error. The default page size is 10 items per page.
{% endhint %}

## Connections

Pagination for references follows the Relay Connection specification and supports forward pagination using the `first` and `after` arguments.

To paginate through all results, use the `endCursor` from the previous response as the `after` argument in your next request. You can see if there are more pages by checking that `hasNextPage` is `true`.

{% tabs %}
{% tab title="GraphQL" %}
{% code lineNumbers="true" %}

```graphql
query($cursor: String) {
  allContent(
    first: 2
    after: $cursor
  ) {
    items {
      id
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code lineNumbers="true" %}

```json
{
  "data": {
    "allContent": {
      "items": [{
        "id": "abc"
      }, {
        "id": "abc123"
      }],
      "pageInfo": {
        "endCursor": "eyAiaWQiOiAiYWJjMTIzIiwgInZhcmlhbnQiOiBudWxsLCAiX190eXBlU2NoZW1hQWxpYXMiOiAicGFnZSIgfQo=",
        "hasNextPage": true
      }
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The returned cursor is only valid for the specified [`orderBy`](/umbraco-compose/apis/graphql/sorting.md) fields. Changing them invalidates existing cursors for the new fields. You must request a new cursor from `{ edge { cursor } }` field, or the page info's `startCursor` or `endCursor` fields.
{% endhint %}

## Lists

For nested or embedded arrays, `skip` and `first` can be used for pagination.

{% tabs %}
{% tab title="GraphQL" %}
{% code lineNumbers="true" %}

```graphql
query {
  allContent(
    first: 2
  ) {
    items {
      id
      ... on Page {
        blocks(skip: 5, first: 2) {
          ... on Banner {
            name
          }
        }
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
{% code lineNumbers="true" %}

```json
{
  "data": {
    "allContent": {
      "items": [{
        "id": "abc",
        "blocks": [{
          "name": "Block 6"
        },{
          "name": "Block 7"
        }]
      }]
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Complexity Limits

The GraphQL API implements a complexity-based rate-limiting system. Each scalar field adds 1 to the cost. Each reference level adds 1 to the scalar cost, multiplied by the number of items fetched in a collection. For example, if you limit your query to fetch `5` items and `3` fields, the total cost is `15`.

The total complexity cost is limited to 15.000.

{% hint style="info" %}
The cost is calculated before the query is executed. It is based on the potential number of items and not the actual items returned from a query.
{% endhint %}

The total cost of a query is returned in the `Umb-GraphQL-Query-Cost` response header.

When a query exceeds this limit, the API will return an error:

```json
{
  "errors": [
    {
      "message": "Query is too complex to execute. Complexity is 32102; maximum allowed on this endpoint is 15000.",
      "extensions": {
        "code": "COMPLEXITY",
        "codes": [
          "COMPLEXITY"
        ]
      }
    }
  ]
}
```

Optimize your queries using one or more of the options listed below:

* Reduce the number of fields requested.
* Limit the depth of nested references.
* Use pagination to reduce the number of items retrieved per query.

## Error Handling

When making pagination requests, it is worth keeping an eye out for the following pitfalls:

* Requesting more than 100 items per page will result in an error.
* Using invalid cursors will result in an error.
* Invalid `skip` or `first` values (for example, negative numbers) will result in errors.

Example GraphQL error response for an invalid page size:

```json
{
  "errors": [
    {
      "message": "Invalid value for argument 'first' of field 'content'. Value cannot be greater than 100",
      "locations": [
        {
          "line": 2,
          "column": 18
        }
      ],
      "extensions": {
        "code": "INVALID_VALUE",
        "codes": [
          "INVALID_VALUE"
        ],
        "number": "5.6"
      }
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.umbraco.com/umbraco-compose/apis/graphql/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.