> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginating API results

> Retrieving particular ranges of data

API endpoints which are expected to return large numbers of results will use pagination to return a limited number of items at a time.

Depending on the endpoint, pagination will be implemented through either limit/offset pagination, or
cursor-based pagination.

## Limit/offset pagination

When using limit/offset pagination, two parameters are used to provide pagination functionality:

* `limit` controls the maximum number of results that an endpoint can return. The default value for limit is documented on each specific endpoint.
* `offset` controls how many values to skip over in the result set. By default, it is always 0.

When querying all results, your initial call should pass an `offset` value of 0. If the number of results you
receive is less than the value of the `limit` parameter (or the default limit if none was passed explicitly), you have
reached the end of the result set and can end pagination. Otherwise, make another API call with a new
`offset` value set to the previous `offset` + `limit` to get the next page, and then repeat until
you are at the end of the list.

For example, if there were 122 records available, your queries would look something like this for a `GET` endpoint using query parameters.

```http theme={"system"}
GET /v2/notes?limit=50             # Results 1 to 50
GET /v2/notes?limit=50&offset=50   # Results 51 to 100
GET /v2/notes?limit=50&offset=100  # Results 101 to 122, less than limit, stop here
```

For a `POST` endpoint using a body, your requests would look like this.

```http theme={"system"}
POST /v2/objects/people/records/query

{
  "limit": 50,
  "offset": 50
}
```

## Cursor-based pagination

Cursor-based pagination is implemented through the `limit` and `cursor` parameters. You will also
receive a `next_cursor` value in the API response.

* `cursor` should only be set to the opaque cursor value provided in the API response and will be used to get the next page of results.
* `limit` is the same as in limit/offset pagination; it controls the maximum number of results that
  an endpoint can return.

Your initial request should omit the `cursor` parameter and specify a `limit` value (or rely on the
endpoint's default). Your response will include `pagination.next_cursor` which you should use in
your next request by passing it as the `cursor` parameter. It is important to keep the limit as
well as any filter parameters consistent between requests to avoid receiving unexpected results.

For example, to call our list meetings endpoint, you would do the following:

```http theme={"system"}
GET /v2/meetings?limit=50
GET /v2/meetings?limit=50&cursor=cursor-1
GET /v2/meetings?limit=50&cursor=cursor-2
```

##### Example response

```jsonc theme={"system"}
{
  "data": [
    /* meeting results here */
  ],
  "pagination": {
    "next_cursor": "opaque-cursor-value-here"
  }
}
```