---
title: "Analytics API Guide"
url: "https://support.sardius.media/knowledge-base/analytics-api-guide"
category: "Analytics"
updated: 2026-08-20
summary: "This guide explains how to call Sardius analytics endpoints to build different workflows, such as Live Viewership Counts."
---

# Analytics API Guide

> **Note:** In order to use the Analytics API, you will first need to [create an API Key](https://support.sardius.media/knowledge-base/create-an-api-key).

### **Overview**

This guide explains how to call **Sardius analytics endpoints** to build:

- **Unique / Total viewers**
- **USA:** Top 5 states
- **Global:** Top 5 countries _(excluding the US)_

#### **Prerequisites**

Sardius will provide:

- `accountId`
- Bearer API key

Send this header on every request:

Authorization: Bearer <api-key>

**Base URL**

<https://api.sardius.media/analytics/{accountId}>

### **Endpoint recipes**

#### **1) Unique / Total Viewers**

Request

GET /analytics/{accountId}/youbora?fromDate=last5minutes\&metrics=views,uniques\&operation=reducejoin

**What this returns**

- One aggregate total for `views`
- One aggregate total for `uniques`

**How to parse**

1. Read `const metrics = response.data[0].metrics`.
2. Find metric blocks:
   - `viewsMetric = metrics.find(m => m.code === "views")`
   - `uniquesMetric = metrics.find(m => m.code === "uniques")`
3. Extract values safely:
   - `views = viewsMetric?.values?.[0]?.data?.[0]?.value ?? 0`
   - `uniques = uniquesMetric?.values?.[0]?.data?.[0]?.value ?? 0`

**Sample interpretation**

- `views = 206` _(total plays in window)_
- `uniques = 23` _(unique users in window)_

#### **2) USA Top 5 States**

Request

GET /analytics/{accountId}/youbora/list/state_province?fromDate=last5minutes\&metrics=views,uniques\&country=United%20States\&limit=5

**What this returns**

- Ranked rows by `state_province` for each metric (`views`, `uniques`)

**How to parse**

1. Read `const metrics = response.data[0].metrics`.
2. Find metric blocks:
   - `viewsMetric = metrics.find(m => m.code === "views")`
   - `uniquesMetric = metrics.find(m => m.code === "uniques")`
3. Convert both arrays to maps keyed by `state_province`.
4. Build combined rows:
   - `{ label: state_province, views, uniques }`
5. Drop invalid rows:
   - blank label
   - `views === 0 && uniques === 0`
6. Keep first 5 rows.

**Sample interpretation**

- `Kansas = views 115, uniques 7`
- `Missouri = views 8, uniques 3`
- `Texas = views 1, uniques 1`
- `Virginia = views 1, uniques 1`

#### **3) Global Top 5 Countries (excluding US)**

Request

GET /analytics/{accountId}/youbora/list/country?fromDate=last5minutes\&metrics=views,uniques\&limit=10

**Why `limit=10`**

If `United States` is in the results and must be excluded, you still want enough rows left to display 5 non‑US countries.

**How to parse**

1. Parse rows into `{ label: country, views, uniques }`.
2. Remove rows where `label === "United States"`.
3. Sort remaining rows by `views` descending _(if needed)_.
4. Keep first 5 non‑US rows.

**Sample interpretation (before exclusion)**

- `United States = views 125, uniques 12`
- `Paraguay = views 55, uniques 6`
- `Argentina = views 18, uniques 3`
- `United Kingdom = views 7, uniques 1`
- `Egypt = views 1, uniques 1`

If US is excluded, output starts with:

- `Paraguay`, `Argentina`, `United Kingdom`, `Egypt`, ...

### **Shared response rules**

- `data[0].dimensions` confirms applied filters (for example `country = United States`).
- `data[0].metrics` contains one block per requested metric code.
- `offset` is an NPAW response field, not a pagination cursor you should reuse.
- Join `views` and `uniques` by label (`country` / `state_province`), not by array index.
- If fewer than 5 valid rows are returned, display available rows only.

### **Choosing a time window (**_fromDate_**)**

Use these defaults unless you need a different reporting window:

- **Live / “callout board”:** `last5minutes`
- **Less noisy near‑live:** `lasthour` or `last3hours`
- **Historical context:** `last30Days`

If omitted, Sardius defaults to `last6hours`.

### **cURL examples**

Replace placeholders before running.

curl --request GET \\
  --url "<https://api.sardius.media/analytics/{accountId}/youbora?fromDate=last5minutes&metrics=views,uniques&operation=reducejoin>" \\
  --header "Authorization: Bearer <api-key>"

curl --request GET \\
  --url "<https://api.sardius.media/analytics/{accountId}/youbora/list/state\_province?fromDate=last5minutes&metrics=views,uniques&country=United%20States&limit=5>" \\
  --header "Authorization: Bearer <api-key>"

curl --request GET \\
  --url "<https://api.sardius.media/analytics/{accountId}/youbora/list/country?fromDate=last5minutes&metrics=views,uniques&limit=10>" \\
  --header "Authorization: Bearer <api-key>"

### **Troubleshooting**

- `401/403`: Check API key and account access scope.
- Empty US states:
  - Confirm `country=United%20States`.
  - Filter out blank `state_province`.
- No data in short windows:
  - Increase window (`lasthour`, `last3hours`, or `last24hours`).
- Global excluding US:
  - Remove `"United States"` client-side before selecting top 5 non‑US rows.

> **Tip:** For our full API Guide, please [click here](https://docs.sardius.media/reference/getyouboraanalytics).