# Pagination

To ensure fast and reliable performance, the Springstreet API uses pagination to handle large sets of results. Instead of returning thousands of records in a single response, the API delivers data in "pages."

Pagination is controlled by a simple `page` query parameter included in the URL of your `GET` request.

#### Controlling Pagination

To request a specific page of results, include the `page` parameter in the URL's query string.

| Parameter | Type    | Required | Description                                                                         |
| --------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `page`    | integer | No       | The page number you wish to retrieve. If omitted, the API will default to page `1`. |

#### Reading the Response

Every successful paginated response will contain a `response_metadata` object. This object provides all the information you need to navigate through the full set of results.

| Field       | Type    | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `page`      | integer | The page number of the results in the current response. |
| `page_size` | integer | The number of items returned per page.                  |
| `next_page` | integer | Identify if there are more results on the next page.    |

**Example Response for Page 1**

After making a request, the response indicates you are on page `1` and there are additional pages available. If `next_page` was `false` then you would be on the final page of data.

JSON

```json
{
    "ucc_liens": [
        // ... 5 lien results for page 1
    ],
    "response_metadata": {
        "page": 1,
        "page_size": 10,
        "next_page": true,
        "timestamp": "2026-01-01T00:00:00",
        "request_id": "xyz",
        "data_source_last_updated": "2026-01-01T00:00:00",
        "api_version": "1.2.0"
    }
}
```

**Example Request for Specific Page (i.e Page 2)**

To get the second page of results, you would set the `page` parameter to `2`.

Bash

```bash
curl --location 'https://api.springstreet.io/filings/recent-by-state?state=TX&page=2' \
--header 'x-api-key: YOUR_API_KEY'
```

#### How to Loop Through All Pages

Your application should continue making requests and incrementing the `page` parameter until the `next_page` equals `false`.

1. Make your initial request (e.g., `...&page=1`).
2. Process the results from the response.
3. Check the `pagination` object.
4. If `next_page = true` , make a new request with `page` incremented by one (e.g., `...&page=2`).
5. Repeat this process until you have retrieved the final page.


---

# 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://springstreet.gitbook.io/springstreet.io/api/getting-started/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.