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

# Analytics

> Know what, when and how much

Our analytics divided with "scopes" - account, group, and link.

```
GET /v1/analytics                          ← account
GET /v1/groups/{id}/analytics              ← group
GET /v1/landings/{id}/analytics            ← one landing page
GET /v1/redirects/{id}/analytics           ← one redirect

GET …/analytics/series                     ← a chart over time
GET …/analytics/breakdown                  ← the full top for one dimension
```

All three endpoints require `start_date`, `end_date` and `timezone`. See
[Dates and time](/api-v1/api-v1/timestamps) .

Account and group scopes cover active links with analytics attached.

## Overview

### Summary

```json theme={null}
{
  "object": "analytics",
  "visitors": 1240,
  "visits": 1580,
  "countries": [{ "name": "US", "visitors": 420 }],
  "referrers": [],
  "channels": [],
  "browsers": [],
  "operating_systems": [],
  "devices": [],
  "activity": { "by_hour": [], "by_weekday": [] },
  "clicks": 310,
  "clicks_by_widget": [
    { "widget_id": "wdg_b269…", "type": "dual", "url": "https://…", "side": "left", "clicks": 180 }
  ],
  "direct_button_clicks": 64,
  "tease_chat": { "message_1": 840, "message_2": 390, "redirects": 95 }
}
```

* `referrers`, `channels`, `browsers`, `operating_systems` and `devices` inside Summary are capped at the top 10. For full results use Breakdown.
* **`activity`** is two projections of a weekday × hour grid — `by_hour` (24) and `by_weekday`
  (7) — cut in the timezone you pass.
* **`tease_chat`** is the funnel `message_1 → message_2 → redirects`. On a group or the account
  these are sums across landing pages.

#### Clicks Analytics

`clicks_by_widget`, landing page scope only.

**A row is a unique combination of `widget_id + type + url + side`, not a widget.**

```json theme={null}
"clicks": 310,
"clicks_by_widget": [
  { "widget_id": "wdg_aaa", "type": "card", "url": "https://…/kate", "side": null, "clicks": 60 },
  { "widget_id": "wdg_bbb", "type": "card", "url": "https://…/kate", "side": null, "clicks": 40 },
  { "widget_id": null,      "type": "card", "url": "https://…/kate", "side": null, "clicks": 210 }
]
```

* `widget_id` could be `null` on landing pages created before 11 August 2026. This clicks are handled with unknown source.
* **`widget_id` may repeat.** If a widget's link changed, its old and new clicks land in separate
  rows under the same id.
* `side` is filled only for `dual` widgets, naming which half was clicked.

### Series

```json theme={null}
{
  "object": "analytics_series",
  "metric": "pageviews",
  "interval": "day",
  "timezone": "Europe/Belgrade",
  "segmentation": "link",
  "series": [
    {
      "segment": { "type": "link", "id": "lnd_5aec…", "url": "https://teasy.link/kate" },
      "points": [{ "time": "2026-08-13T22:00:00Z", "count": 42 }]
    }
  ]
}
```

* `metric` is `pageviews` or `clicks`. **`clicks` on a redirect scope returns
  `400 invalid_request`** — redirects have no widgets.
* `interval` is `hour`, `day` or `month`, chosen by the server from your range and reported back.
  You cannot set it.
* Without `segmentation`, `points` sits at the top level and there is no `series`.
* `segmentation=link` works on the account and group scopes only; elsewhere it returns
  `400 invalid_request`. At most 20 series, ordered by total.
* Empty buckets are omitted, not returned as zeroes.

#### The bucket timestamp is not the bucket date

As stated on the [Date and Time](/api-v1/api-v1/timestamps.mdx) page, the `time` field is returned by us in UTC. However, despite this, it is correctly adjusted according to the time zone you provided in the request.

| You request               | First timestamp will be |
| ------------------------- | ----------------------- |
| Day 14 Aug 2026, Belgrade | 2026-08-13T22:00:00Z    |
| Month Aug 2026, Belgrade  | 2026-07-31T22:00:00Z    |

### Breakdown [Reference](/api-v1/api-v1/api-reference/)

```json theme={null}
{
  "object": "analytics_breakdown",
  "dimension": "country",
  "items": [{ "name": "US", "visitors": 420 }]
}
```

`dimension` is one of `country`, `city`, `device`, `browser`, `os`, `referrer`, `channel`.
`limit` defaults to 10, maximum 100.

# Freshness and limits

**Responses are cached for 60 seconds**, so figures may lag by up to a minute.

Your plan caps how far back a period may reach; exceeding it returns
`403 analytics_range_exceeds_plan_limit` rather than a silently shortened window. Comparison
against a previous period is not exposed in v1.