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

# Filtering

> Narrow a query, and understand what each filter costs.

Analytics endpoints share a large common set of filters. They combine with AND — a query filtered to `countries` and `devices` returns clicks matching both.

## The filter set

| Filter | Narrows to |
| - | - |
| `countries`, `regions`, `cities` | Where the click came from |
| `devices`, `browsers`, `operating_systems` | What it came from |
| `referrers`, `referrer_urls` | Where it arrived from |
| `domains` | Which branded domain served it |
| `destination_urls` | Where it was sent |
| `shortlink_urls`, `shortlink_back_halfs`, `shortlinks` | Which links |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id` (as `utm_sources`, `utm_mediums`, …) | UTM values on the destination |
| `link_type` | Links versus QR codes (org endpoints) |

Values are passed as JSON arrays:

```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=referrer&countries=["US","CA"]&devices=["mobile"]" \
  -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=referrer&countries=[\"US\",\"CA\"]&devices=[\"mobile\"]", {
  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=referrer&countries=["US","CA"]&devices=["mobile"]',
    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=referrer&countries=[\"US\",\"CA\"]&devices=[\"mobile\"]"
	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=referrer&countries=[\"US\",\"CA\"]&devices=[\"mobile\"]")
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=referrer&countries=["US","CA"]&devices=["mobile"]');
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);
```

> [!TIP]
>
> `get_org_metric_filter_values` returns the values actually present in your data for a dimension. Use it to build filter menus rather than guessing at spellings — filters match what was recorded, and a country that never appears will quietly return zero rows.

## Two query engines

This is the part worth internalising, because it explains an error you will otherwise find baffling.

Most queries are answered from **pre-aggregated rollups**: click counts already grouped by day and dimension. Fast, cheap, and what you get by default.

Some filters cannot be answered from rollups, because the rollup does not carry that dimension. Those force a **raw event scan** — same results, slower on wide date ranges.

`get_org_metrics_batch` exists specifically to fetch several dimensions in one rollup query, so it cannot fall back:

```json theme={null}
{
  "data": {
    "status": "error",
    "message": "Batch metrics require rollup path; use individual metric endpoints with active filters."
  }
}
```

That is the batch endpoint telling you a filter you passed is not rollup-answerable. Split into individual `get_org_metrics_aggregation` calls, which will take the raw path and succeed.

> [!NOTE]
>
> Note the shape: `status: "error"` inside a `200` `data` envelope, not an error envelope. Check it explicitly if you use the batch endpoint.

## Keeping queries fast

> [accordion] Ask for the range you need
>
> Query cost scales with the window. Thirteen months to render a thirty-day chart is thirteen times the work for the same picture.

> [accordion] Batch when unfiltered
>
> Four dimensions for a dashboard is one `get_org_metrics_batch` call, not four round trips — as long as no raw-only filter is involved.

> [accordion] Cache what does not move
>
> Yesterday's totals will not change. Historical windows can be cached indefinitely; only ranges touching today need refreshing.

> [accordion] Filter before paginating
>
> Narrowing with filters is cheaper than paging through everything and discarding rows client-side.

## A composed query

```python theme={null}
import json

params = {
    "date_from": "2026-01-01",
    "date_to": "2026-01-31",
    "metric": "referrer",
    "per_page": 50,
    "timezone": "America/New_York",
    "countries": json.dumps(["US"]),
    "devices": json.dumps(["mobile"]),
    "utm_sources": json.dumps(["newsletter"]),
}

response = requests.get(
    f"{BASE}/analytics/get_org_metrics_aggregation",
    headers=HEADERS,
    params=params,
)
```

Mobile traffic from the US that arrived from the newsletter, broken down by referrer, fifty rows at a time, bucketed in Eastern time.


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