# Pagination

The API implements pagination. By default, the page size is set based on your subscription. You can change the size of the page with the `page_size` parameter, up to the maximum allowed by your subscription. For instance, to access the second page where each page has 100 rows and you are using offset based pagination, append `?page=2&page_size=100` to your request URL.

Keep in mind that retrieving many records from large datasets might necessitate multiple requests. See below for information on how to determine if there is a next page.

### Offset vs Cursor Pagination

* The API supports both offset and cursor pagination.
* Cursor pagination is used when the `cursor` parameter is provided.
* Cursor pagination is more efficient than offset pagination for large datasets because it doesn't require the API to scan through all the records to find the next page.
* For cursor pagination, for the first request, append `cursor=""` to your request to get the first page. For subsequent requests, use the `cursor` value from the meta data of the previous response.
* Offset pagination requires sending the `page` parameter to specify the page number.

#### JSON Response Format <a href="#json-response-format" id="json-response-format"></a>

When using the JSON response format, the API will return a meta object in the response that includes information about the current page, the limit, whether there are more records available (hasNextPage), and the cursor for using cursor pagination.

```json
{
  "status": "success",
  "data": [...],
  "meta": {
    "page": 1,
    "page_size": 50000,
    "limit": 1000,
    "hasNextPage": true
    "cursor": "dGhpcyBpcyBhIGxvbmcgc3RyaW5n"
  }
}
```

#### CSV Response Format <a href="#csv-response-format" id="csv-response-format"></a>

When using the CSV response format, the API will return the pagination information as headers in the response:

* `X-Page`: The current page number
* `X-Page-Size`: The page size
* `X-Limit`: The maximum number of rows to return across all pages
* `X-Has-Next-Page`: A boolean value indicating whether there are more records available


---

# 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.gridstatus.io/developers/concepts/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.