> ## 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.

# Pagination

> Walk a list endpoint without missing records or re-reading them.

Every list endpoint paginates the same way: `page` and `per_page` on the request, counts on the response.

## Request

| Parameter | Default | Maximum | Notes |
| - | - | - | - |
| `page` | `1` | — | 1-based, not 0-based |
| `per_page` | `10` | `100` | Values above 100 are clamped |

> [!NOTE]
>
> `per_page=500` returns 100 records and a `200`, not an error. The response echoes the `per_page` that was actually applied, so read it back rather than assuming you got what you asked for.

## Response

The collection sits under a name matching the resource — `links`, `qrcodes`, `campaigns`, `tags`, `utm_templates`, `dynamic_link_templates` — alongside four counts:

```json theme={null}
{
  "data": {
    "links": [],
    "total_count": 247,
    "total_pages": 25,
    "current_page": 1,
    "per_page": 10
  }
}
```

| Field | Meaning |
| - | - |
| `total_count` | Records matching your filters, across all pages |
| `total_pages` | Pages at this `per_page` |
| `current_page` | The page you are on |
| `per_page` | Records per page, after clamping |

## Walking every page

```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")
  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* allLinks(apiKey, filters = {}) {
  let page = 1;

  while (true) {
    const params = new URLSearchParams({ page, per_page: 100, ...filters });
    const response = await fetch(
      `https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?${params}`,
      { headers: { "X-API-Key": apiKey } }
    );
    const { data } = await response.json();

    yield* data.links;

    // total_pages already accounts for the clamped per_page.
    if (page >= data.total_pages) break;
    page++;
  }
}
```

```python Python theme={null}
def all_links(api_key, **filters):
    page = 1
    while True:
        response = requests.get(
            "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks",
            headers={"X-API-Key": api_key},
            params={"page": page, "per_page": 100, **filters},
        )
        data = response.json()["data"]

        yield from data["links"]

        # total_pages already accounts for the clamped per_page, so this
        # terminates correctly even if per_page was lowered.
        if page >= data["total_pages"]:
            break
        page += 1
```

```go Go theme={null}
func AllLinks(apiKey string, visit func(json.RawMessage) error) error {
	page := 1

	for {
		url := fmt.Sprintf(
			"https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?page=%d&per_page=100",
			page)

		req, _ := http.NewRequest("GET", url, nil)
		req.Header.Set("X-API-Key", apiKey)

		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			return err
		}

		var body struct {
			Data struct {
				Links      []json.RawMessage `json:"links"`
				TotalPages int               `json:"total_pages"`
			} `json:"data"`
		}
		err = json.NewDecoder(resp.Body).Decode(&body)
		resp.Body.Close()
		if err != nil {
			return err
		}

		for _, link := range body.Data.Links {
			if err := visit(link); err != nil {
				return err
			}
		}

		// total_pages already accounts for the clamped per_page.
		if page >= body.Data.TotalPages {
			return nil
		}
		page++
	}
}
```

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

  page = 1

  loop do
    uri = URI("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks")
    uri.query = URI.encode_www_form(page: page, per_page: 100, **filters)

    data = JSON.parse(
      Net::HTTP.get_response(uri, "X-API-Key" => api_key).body
    )["data"]

    data["links"].each { |link| yield link }

    # total_pages already accounts for the clamped per_page.
    break if page >= data["total_pages"]
    page += 1
  end
end
```

```php PHP theme={null}
<?php
function all_links(string $apiKey, array $filters = []): Generator
{
    $page = 1;

    do {
        $query = http_build_query(['page' => $page, 'per_page' => 100] + $filters);
        $ch = curl_init(
            "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?$query"
        );
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);

        $data = json_decode(curl_exec($ch), true)['data'];
        curl_close($ch);

        yield from $data['links'];

        // total_pages already accounts for the clamped per_page.
        $page++;
    } while ($page <= $data['total_pages']);
}
```

> [!WARNING]
>
> Stop on `total_pages`, not on an empty array. A page can come back short of `per_page` without being the last one, and looping until you see zero records costs an extra request every time.

## Sorting

Two parameters control order:

| Parameter | Values | Default |
| - | - | - |
| `sort_by` | `name`, `most_recent`, `last_modified` | `name` |
| `order` | `asc`, `desc` | `asc` |

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc" \
  -H "X-API-Key: dlk_live_..."
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc", {
  headers: { "X-API-Key": "dlk_live_..." },
});
const payload = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc',
    headers={'X-API-Key': 'dlk_live_...'},
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", "dlk_live_...")
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = "dlk_live_..."
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?sort_by=most_recent&order=desc');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . 'dlk_live_...',
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

> [!WARNING]
>
> **There is no `most_clicked`.** Click counts are stored in the analytics system rather than alongside the links, so there is nothing to sort on. To rank by clicks, read [`get_org_metrics_aggregation`](https://docs.dashlink.ai/api-reference/analytics/overview) and order the result yourself.

## Pagination inside analytics

Analytics breakdowns paginate too, but the page parameter is called `current_page` rather than `page`:

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50" \
  -H "X-API-Key: dlk_live_..."
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50", {
  headers: { "X-API-Key": "dlk_live_..." },
});
const payload = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50',
    headers={'X-API-Key': 'dlk_live_...'},
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", "dlk_live_...")
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = "dlk_live_..."
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/analytics/get_org_metrics_aggregation?date_from=2026-01-01&date_to=2026-01-31&metric=country&current_page=1&per_page=50');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . 'dlk_live_...',
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

## A caveat on long walks

Pagination is offset-based, so it reflects the data as it is at the moment each page is read, not a snapshot from when you started. If links are being created while you page through, a record can move between pages and be seen twice or missed.

For a consistent view of a changing list, filter to a closed window with `date_from` and `date_to` so new records fall outside it:

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc" \
  -H "X-API-Key: dlk_live_..."
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc", {
  headers: { "X-API-Key": "dlk_live_..." },
});
const payload = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc',
    headers={'X-API-Key': 'dlk_live_...'},
)
payload = response.json()
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", "dlk_live_...")
	resp0, err0b := http.DefaultClient.Do(req0)
	if err0b != nil {
		panic(err0b)
	}
	defer resp0.Body.Close()
	body0, _ := io.ReadAll(resp0.Body)
	fmt.Println(string(body0))
}

```

```ruby Ruby theme={null}
require "net/http"
require "json"
require "uri"

uri0 = URI("https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = "dlk_live_..."
response0 = Net::HTTP.start(uri0.hostname, uri0.port, use_ssl: true) do |http|
  http.request(request0)
end
payload0 = JSON.parse(response0.body)
```

```php PHP theme={null}
<?php
$ch0 = curl_init('https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?date_from=2026-01-01&date_to=2026-01-31&per_page=100&sort_by=most_recent&order=asc');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . 'dlk_live_...',
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```


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