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

# Paging

Some Flare APIs use a common pattern for paging results.
This pattern pairs the `from` request parameter to the `next` response field.

## Using `from` and `next` paging

<Steps>
  <Step title="First Request">
    Perform the first request without specifying `from`.
    This indicates that you want the first page of results.
  </Step>

  <Step title="Subsequent Requests">
    Use the `next` response field from your last response as the
    value for your following request's `from` parameter.
    This indicates that you want the next page of results.

    All parameters other than `from` must remain the same as the original request.

    If `next` is missing from the last response (or is `null`), this means that you viewed all pages.

    <Note>
      Empty pages (no results) does not mean you viewed all pages.
      Some filters (like ignored events) will cause empty pages.
      This means that you should still request the next page even after receiving an empty page.
    </Note>
  </Step>
</Steps>

## The `from` Request Parameter

<ParamField query="from" type="string">
  Used to indicate where to resume paging.

  Should be empty on the first request.
</ParamField>

## The `next` Response field

<ResponseField name="next" type="string">
  The value that should be included in the next request's `from` parameter.

  Most of the time, this is an opaque string.

  The value of the `next` response field can be saved for long periods of time.
  For example if you want to export all results for a given search and then resume
  to fetch new results the next day.
</ResponseField>

## Page size vs number of returned items

Flare APIs can return less results than the requested page size.
This is normal and you should assume that there are still results until you reach a page where `next` is `null`.

## End-to-End Examples

These are end-to-end examples in various programming languages.

<AccordionGroup>
  <Accordion title="Python SDK Example">
    ```python theme={null}
    import os

    from flareio import FlareApiClient
    from flareio.ratelimit import Limiter


    api_key = os.environ.get("FLARE_API_KEY")
    if not api_key:
        raise Exception("Please provide an API key")

    api_client = FlareApiClient(api_key=api_key)

    limiter_default = Limiter.from_seconds(0.25)

    last_from: str | None = None
    fetched_pages: int = 0

    for resp in api_client.scroll(
        method="GET",
        url="/astp/v2/sources",
        params={
            "from": last_from,
        },
    ):
        # Rate limiting (default).
        limiter_default.tick()

        # Get results from the response
        resp_data = resp.json()
        items = resp_data.get("items")

        fetched_pages += 1
        print(f"Fetched page {fetched_pages} ({last_from=}) with {len(items)} items...")

        # Save the last "next" value.
        last_from = resp_data.get("next") or last_from

    print("The last value for 'next' was", last_from)
    ```
  </Accordion>

  <Accordion title="Python Generic Example">
    ```python theme={null}
    import os

    from flareio import FlareApiClient
    from flareio.ratelimit import Limiter


    api_key = os.environ.get("FLARE_API_KEY")
    if not api_key:
        raise Exception("Please provide an API key")

    api_client = FlareApiClient(api_key=api_key)

    limiter_default = Limiter.from_seconds(0.25)

    from_: str | None = None
    fetched_pages: int = 0

    while True:
        limiter_default.tick()

        params: dict = {}
        if from_:
            params["from"] = from_

        # Fetch the next page
        resp = api_client.get(
            "/astp/v2/sources",
            params=params,
        )
        resp.raise_for_status()

        fetched_pages += 1
        print(f"Fetched {fetched_pages} pages...")

        # Stop if there is no "next" value.
        next_page = resp.json().get("next")
        if not next_page:
            print("The last value for 'next' was", from_)
            break
        else:
            print(f"Next page will be from {next_page}")
            from_ = next_page
    ```
  </Accordion>

  <Accordion title="Go SDK Example">
    ```go theme={null}
    package main

    import (
    	"fmt"
    	"os"
    	"time"

    	"github.com/Flared/go-flareio"
    )

    func main() {
    	client := flareio.NewApiClient(
    		os.Getenv("FLARE_API_KEY"),
    	)

    	fetchedPages := 0

    	for result, err := range client.IterGet(
    		"/astp/v2/sources", nil,
    	) {
    		// Rate Limiting
    		time.Sleep(time.Second * 1)

    		if err != nil {
    			fmt.Printf("unexpected error: %s\n", err)
    			os.Exit(1)
    		}

    		// Handle the response...
    		result.Response.Body.Close()

    		// Print the status
    		fetchedPages = fetchedPages + 1
    		fmt.Printf(
    			"Fetched %d page(s) of astp Sources, next=%s\n",
    			fetchedPages,
    			result.Next,
    		)
    	}

    }
    ```
  </Accordion>
</AccordionGroup>