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

# Metrics and breakdowns

> Which dimensions you can group by, and why some come back locked.

A breakdown groups clicks by one dimension and returns them ranked. The dimension is the `metric` parameter:

```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&per_page=20" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```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&per_page=20", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

```python Python theme={null}
import os
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&per_page=20',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

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

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

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&per_page=20"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	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&per_page=20")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
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&per_page=20');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

## Dimensions

| Group | `metric` values |
| - | - |
| Location | `country`, `region`, `city` |
| Technology | `device`, `browser`, `operating_system` |
| Acquisition | `referrer`, `domain` |
| Campaign | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id` |

The campaign-scoped time-series endpoints use a different, longer naming — `clicks_by_country`, `clicks_by_device`, `by_time_of_the_day` and so on. The error message lists the accepted values for whichever endpoint rejected you, so read it rather than assuming the two sets match.

## Several at once

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/analytics/get_org_metrics_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

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

response = requests.get(
    'https://api.dashlink.ai/api/v1/analytics/get_org_metrics_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

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

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

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/analytics/get_org_metrics_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	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_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
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_batch?date_from=2026-01-01&date_to=2026-01-31&metrics=device,browser,country,referrer&per_page=10');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

`metrics` is comma-separated. One query instead of four, which is the difference between a dashboard that loads and one that staggers.

## Locked breakdowns

Location detail, technology and the UTM dimensions are plan features. On a plan without them you do not get an error — you get a well-formed response carrying sample data and a lock flag:

```json theme={null}
{
  "data": {
    "analytics": {
      "locked": true,
      "required_access_level": "full",
      "required_plan": "Plus",
      "locked_message": "City analytics are available on the Plus plan and above.",
      "metric_clicks": [ ]
    }
  }
}
```

This is deliberate: a gated widget still has a shape to render behind a blur, and the server stays the source of truth for what is gated.

> [!WARNING]
>
> The rows alongside `"locked": true` are **sample data, not your traffic**. Always check the flag before displaying or storing figures. The flag appears on both the payload and the nested `analytics` object, because callers commonly keep only the inner one.

```python theme={null}
payload = response.json()["data"]
analytics = payload.get("analytics", payload)

if analytics.get("locked"):
    render_upgrade_prompt(analytics["locked_message"])
else:
    render_chart(analytics["metric_clicks"])
```

Batch calls partition rather than refuse: allowed dimensions come back with real numbers, gated ones come back locked, in the same response.

## Paginating a breakdown

`current_page` and `per_page`, with `per_page` defaulting low — 5 on most breakdown endpoints. Raise it deliberately:

```bash theme={null}
&current_page=2&per_page=50
```

## Time series

```bash cURL theme={null}
curl -X GET "https://api.dashlink.ai/api/v1/analytics/get_org_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day" \
  -H "X-API-Key: $DASHLINK_API_KEY"
```

```javascript Node.js theme={null}
const response = await fetch("https://api.dashlink.ai/api/v1/analytics/get_org_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day", {
  headers: { "X-API-Key": process.env.DASHLINK_API_KEY },
});
const payload = await response.json();
```

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

response = requests.get(
    'https://api.dashlink.ai/api/v1/analytics/get_org_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day',
    headers={'X-API-Key': os.environ["DASHLINK_API_KEY"]},
)
payload = response.json()
```

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

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

func main() {
	endpoint0 := "https://api.dashlink.ai/api/v1/analytics/get_org_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day"
	req0, err0 := http.NewRequest("GET", endpoint0, nil)
	if err0 != nil {
		panic(err0)
	}
	req0.Header.Set("X-API-Key", os.Getenv("DASHLINK_API_KEY"))
	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_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day")
request0 = Net::HTTP::Get.new(uri0)
request0["X-API-Key"] = ENV.fetch("DASHLINK_API_KEY")
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_clicks_users_over_time?date_from=2026-01-01&date_to=2026-03-31&granularity=day');
curl_setopt($ch0, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch0, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch0, CURLOPT_HTTPHEADER, [
    "X-API-Key: " . getenv("DASHLINK_API_KEY"),
]);
$payload0 = json_decode(curl_exec($ch0), true);
curl_close($ch0);
```

`granularity` accepts `minute`, `hour`, `day`, `month` and `year`, though not every endpoint accepts all five — the campaign endpoints are narrower. Omit it and one is chosen from the width of your range, which is usually what you wanted.

`get_org_clicks_by_hour` is a different question: clicks by hour of day, aggregated across the range, for finding when your audience is active rather than how traffic trended.

## Beyond clicks

* `get_org_routing_analytics`, `get_campaign_routing_analytics`, `get_shortlink_routing_analytics` — how [routing rules](https://docs.dashlink.ai/guides/links/routing-rules.md) resolved, and which rules are doing nothing
* `get_shortlink_password_attempts` — attempts against a [password-protected link](https://docs.dashlink.ai/guides/links/password-protection.md), successful and not


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