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

# Paginating reliably

> Reading a large collection without missing records or reading them twice.

[Pagination](https://docs.dashlink.ai/api-reference/concepts/pagination.md) documents the parameters and the response fields. This covers what goes wrong at scale and how to avoid it.

## The list is moving while you read it

Pages are computed per request. If records are created or deleted between page 3 and page 4, the boundary shifts: a deletion pulls a record back onto a page you already read, an insertion pushes one onto a page you have passed.

Most of the time this does not matter. When it does — a reconciliation, an export you will diff — mitigate it:

> [accordion] Sort by something stable
>
> `sort_by=name` is stable under new writes. `most_recent` puts new records at the front of page 1 and shuffles everything back by one, which is the worst case for a paged read.

> [accordion] Deduplicate by id
>
> Keep a set of ids as you go. A record you have already seen is a shift, not a duplicate to store.

> [accordion] Take fewer, larger pages
>
> `per_page=100` gives shifts a quarter of the opportunities that `per_page=25` does.

> [accordion] Read the whole thing, then act
>
> Collect first and process after, rather than mutating records as you page through them — editing page 2 while reading page 3 is how a job skips half its input.

## A generator that handles both hazards

```bash cURL theme={null}
page=1
while :; do
  body=$(curl -sS -G "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks" \
    -H "X-API-Key: $DASHLINK_API_KEY" \
    --data-urlencode "page=$page" \
    --data-urlencode "per_page=100" \
    --data-urlencode "sort_by=name" \
    --data-urlencode "order=asc")
  echo "$body" | jq -e '.error' >/dev/null && {
    echo "$body" | jq -r '.error.message' >&2
    exit 1
  }
  echo "$body" | jq -c '.data.links[]'
  total=$(echo "$body" | jq '.data.total_pages')
  [ "$page" -ge "$total" ] && break
  page=$((page + 1))
done
```

```javascript Node.js theme={null}
async function* iterLinks(client, filters = {}) {
  const seen = new Set();
  let page = 1;

  while (true) {
    const data = await client.call("GET", "shortlinks/get_shortlinks", {
      query: {
        page,
        per_page: 100,
        sort_by: "name", // stable under concurrent writes
        order: "asc",
        ...filters,
      },
    });

    for (const link of data.links) {
      if (!seen.has(link.name)) {
        seen.add(link.name);
        yield link;
      }
    }

    // total_pages reflects the clamped per_page, so this terminates
    // correctly even when a larger per_page was lowered to 100.
    if (page >= data.total_pages) break;
    page++;
  }
}
```

```python Python theme={null}
def iter_links(client, **filters):
    seen = set()
    page = 1

    while True:
        data = client.call(
            "GET",
            "shortlinks/get_shortlinks",
            params={
                "page": page,
                "per_page": 100,
                "sort_by": "name",   # stable under concurrent writes
                "order": "asc",
                **filters,
            },
        )

        for link in data["links"]:
            if link["name"] not in seen:
                seen.add(link["name"])
                yield link

        # total_pages reflects the clamped per_page, so this terminates
        # correctly even when a larger per_page was lowered to 100.
        if page >= data["total_pages"]:
            break
        page += 1
```

```go Go theme={null}
func IterLinks(c *Client, filters url.Values, visit func(Link) error) error {
	seen := map[string]bool{}
	page := 1

	for {
		query := url.Values{
			"page":     {strconv.Itoa(page)},
			"per_page": {"100"},
			"sort_by":  {"name"}, // stable under concurrent writes
			"order":    {"asc"},
		}
		for k, v := range filters {
			query[k] = v
		}

		raw, err := c.Call("GET", "shortlinks/get_shortlinks?"+query.Encode(), nil)
		if err != nil {
			return err
		}

		var data struct {
			Links      []Link `json:"links"`
			TotalPages int    `json:"total_pages"`
		}
		if err := json.Unmarshal(raw, &data); err != nil {
			return err
		}

		for _, link := range data.Links {
			if seen[link.Name] {
				continue
			}
			seen[link.Name] = true
			if err := visit(link); err != nil {
				return err
			}
		}

		// total_pages reflects the clamped per_page, so this terminates
		// correctly even when a larger per_page was lowered to 100.
		if page >= data.TotalPages {
			return nil
		}
		page++
	}
}
```

```ruby Ruby theme={null}
def iter_links(client, **filters)
  return to_enum(:iter_links, client, **filters) unless block_given?

  seen = Set.new
  page = 1

  loop do
    data = client.call("GET", "shortlinks/get_shortlinks",
                       page: page,
                       per_page: 100,
                       sort_by: "name", # stable under concurrent writes
                       order: "asc",
                       **filters)

    data["links"].each do |link|
      yield link if seen.add?(link["name"])
    end

    # total_pages reflects the clamped per_page, so this terminates
    # correctly even when a larger per_page was lowered to 100.
    break if page >= data["total_pages"]
    page += 1
  end
end
```

```php PHP theme={null}
<?php
function iter_links(Dashlink $client, array $filters = []): Generator
{
    $seen = [];
    $page = 1;

    do {
        $data = $client->call('GET', 'shortlinks/get_shortlinks', [
            'page' => $page,
            'per_page' => 100,
            'sort_by' => 'name', // stable under concurrent writes
            'order' => 'asc',
        ] + $filters);

        foreach ($data['links'] as $link) {
            if (!isset($seen[$link['name']])) {
                $seen[$link['name']] = true;
                yield $link;
            }
        }

        // total_pages reflects the clamped per_page, so this terminates
        // correctly even when a larger per_page was lowered to 100.
        $page++;
    } while ($page <= $data['total_pages']);
}
```

## Do not page to find one record

Walking every page looking for a back-half is expensive and gets worse as the account grows. Filter server-side:

```python theme={null}
data = client.call(
    "GET", "shortlinks/get_shortlinks",
    params={"search": "spring-sale", "per_page": 10},
)
```

The same applies to counting. `total_count` on page 1 is the answer; you do not need to walk the collection to get it.

```python theme={null}
total = client.call(
    "GET", "shortlinks/get_shortlinks", params={"per_page": 1},
)["total_count"]
```

## Resuming a long job

Store the page number and the filters together. A page number alone is meaningless against a different sort or filter set, and resuming with it will skip records silently.

```python theme={null}
checkpoint = {
    "page": page,
    "filters": filters,
    "sort_by": "name",
    "order": "asc",
}
```

For anything long-running, prefer a date-window checkpoint — "processed everything created before X" — over a page number. Windows survive the collection changing shape; page numbers do not.

## Analytics pagination is separate

Analytics breakdowns use `current_page` and `per_page`, not `page`, and `per_page` defaults to 5 rather than 10. Easy to miss when moving between the two families of endpoints. See [Metrics](https://docs.dashlink.ai/guides/analytics/metrics.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.