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

# Pagination

> Retrieve large datasets efficiently with automatic page breaks.

<Callout icon="map-pin" color="#8b5cf6" iconType="regular">
  * Pagination only applies when requesting linked indicators from threats or feeds. Other API endpoints do not use pagination.
  * Page limits per request vary by plan:
    * Free: 1
    * Pro: 2
    * Team: 4
    * Business/Custom: 10
</Callout>

When working with large datasets, pagination helps you retrieve manageable chunks of data instead of overwhelming responses.
The Pulsedive API automatically breaks large result sets into pages when you request linked indicators from threats or feeds.

***

## How Pagination Works

When your request returns a large number of results, the Pulsedive API automatically splits the response into pages and includes helpful navigation fields:

* `page_current`: Shows which page you are currently viewing (starts at `0`)
* `page_next`: Tells you the next page number to request (only appears when more pages are available)

The first page of a paginated response looks like this:

```json theme={null}
{
  "page_current": 0,
  "page_next": 1,
  "results": [
    {
      "iid": 918421,
      "indicator": "185.220.100.255",
      "type": "ip",
      "risk": "low",
      "stamp_linked": "2018-11-18 11:46:55",
      "summary": {
        "properties": {
          ...
        }
      }
    },
    ...
  ]
}
```

<Note>
  If your results fit on a single page, you won't receive the `page_current` and `page_next` fields.
</Note>

## Retrieving Additional Pages

To get the next page of results, make the same request and add a `page` parameter with the value from `page_next`.
Keep requesting subsequent pages until `page_next` disappears from the response—this means you have reached the end of the data.

<Note>
  Each pagination request counts toward your API rate limits.
  Plan your requests accordingly when working with large datasets.
</Note>

### Example Workflow

This walkthrough demonstrates how to retrieve all linked indicators from a feed using pagination.

<Steps>
  <Step title="Make your initial request">
    This example uses these parameters:

    ```json theme={null}
    {
      "fid": "19",
      "get": "links",
      "pretty": "1",
      "key": "<YOUR_API_KEY>"
    }
    ```

    Make a request to the [`feed.php` endpoint](/api/feed/get-by-id/):

    ```bash theme={null}
    curl "https://pulsedive.com/api/feed.php \
      ?fid=19 \
      &get=links \
      &pretty=1 \
      &key=<YOUR_API_KEY>"
    ```
  </Step>

  <Step title="Check the response for pagination fields">
    The results include `page_current` and `page_next` keys:

    ```json theme={null}
    {
      "page_current": 0,
      "page_next": 1,
      "results": [
        {
          "iid": 918421,
          "indicator": "185.220.100.255",
          "type": "ip",
          "risk": "low",
          "stamp_linked": "2018-11-18 11:46:55",
          "summary": {
            "properties": {
              ...
            }
          }
        },
        ...
      ]
    }
    ```
  </Step>

  <Step title="Request the next page">
    Using the `page_next` value, request the next page with the `page` parameter:

    ```json theme={null}
    {
      "fid": "19",
      "get": "links",
      "pretty": "1",
      "key": "<YOUR_API_KEY>",
      "page": "1"
    }
    ```

    ```bash theme={null}
    curl "https://pulsedive.com/api/feed.php \
      ?fid=19 \
      &get=links \
      &pretty=1 \
      &page=1 \
      &key=<YOUR_API_KEY>"
    ```
  </Step>

  <Step title="Continue until `page_next` is no longer included">
    When results are exhausted, only `page_current` appears:

    ```json theme={null}
        {
          "page_current": 2,
          "results": [
            {
              "iid": 95352,
              "indicator": "191.20.101.211",
              "type": "domain",
              "risk": "medium",
              "stamp_linked": "2021-04-23 05:22:12",
              "summary": {
                "properties": {
                  ...
                }
              }
            },
            ...
          ]
        }
    ```
  </Step>
</Steps>

***

## Troubleshooting

Find answers to common questions about working with paginated responses.

### Can I jump to a specific page?

While you can technically request any page number, we recommend following the sequence provided by `page_next`.
Skipping ahead or accessing pages out of order can lead to inconsistent results, especially if the dataset has changed between requests.

### Can I go back to a previous page?

Paging works in a forward direction only.
To start over, make your original request again (without a `page` parameter) to get page 0.

### How do I know when I've retrieved all the data?

You have reached the final page of results when the API response no longer includes a `page_next` value.