---
title: "Analytics API Reference | Linkbreakers"
description: "Scan and visit numbers: rolling workspace totals, time series, and breakdowns by country, device, hour, link or workflow step, with funnels, A/B splits…"
canonical: "https://linkbreakers.com/help/api/analytics"
---

# Analytics

Scan and visit numbers: rolling workspace totals, time series, and breakdowns by country, device, hour, link or workflow step, with funnels, A/B splits and visitor attributes.

16 entries on this page

### Parameters

`startDate` string (date-time) 

query

Inclusive start timestamp. Without startDate and endDate the request covers all time.

`endDate` string (date-time) 

query

Exclusive end timestamp

`limit` integer (int32) 

query

Maximum number of positions returned, newest first. Defaults to and may not exceed 2000\. total still counts every match.

`linkId` string 

query

Optional link filter (UUID); when omitted covers the whole workspace

`directoryId` string 

query

Optional directory filter (UUID): the links of this directory and of every directory below it. Send at most one of linkId, directoryId and tagId

`tagId` string 

query

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

`countries` array of string 

query

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

### Response

200

`data` array of object

5 child attributes

`accuracyMeters` number (double)

How far off the browser says the position may be, in meters. Absent when the browser did not report it.

`latitude` number (double)

`linkId` string

The link whose workflow asked for it

`longitude` number (double)

`occurredAt` string (date-time)

When the visitor shared it

`total` integer (int32)

Every position matching the request, which exceeds the length of data when the limit cut the list

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/analytics/shared-locations" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "data": [
    {
      "accuracyMeters": 0,
      "latitude": 0,
      "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "longitude": 0,
      "occurredAt": "2026-01-15T09:30:00Z"
    }
  ],
  "total": 0
}
```

### Response

200

`countries` array of object

Every country the workspace's visits came from, most visited first.

2 child attributes

`code` string

ISO 3166-1 alpha-2 code, e.g. "NL".

`name` string

English name, e.g. "Netherlands".

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/analytics/visitor-countries" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "countries": [
    {
      "code": "string",
      "name": "string"
    }
  ]
}
```

### Parameters

`startDate` string (date-time) 

query

Inclusive start timestamp for the aggregation

`endDate` string (date-time) 

query

Inclusive end timestamp for the aggregation

`linkId` string 

query

Optional link filter (UUID); when omitted aggregates workspace-wide

UUID format

`directoryId` string 

query

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`tagId` string 

query

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

`countries` array of string 

query

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

### Response

200

`firstAt` string (date-time)

Timestamp of the first event in the aggregated range

`lastAt` string (date-time)

Timestamp of the last event in the aggregated range

`topCity` string

The top city

`topCountry` string

The top country (ISO code or name)

`topDeviceType` enum

The top device type

Allowed values

* `DEVICE_TYPE_NATIVE` Native QR scanner (no browser capabilities reported)
* `DEVICE_TYPE_MOBILE` Mobile handset browser
* `DEVICE_TYPE_TABLET` Tablet browser
* `DEVICE_TYPE_DESKTOP` Desktop or laptop browser
* `DEVICE_TYPE_UNKNOWN` Unable to classify the device
* `DEVICE_TYPE_UNSPECIFIED` Device type not specified or not yet detected

`totalCities` integer (int32)

Total number of unique cities seen in the events

`totalCountries` integer (int32)

Total number of unique countries seen in the events

`totalDeviceTypes` integer (int32)

Number of unique device types

`totalEvents` integer (int32)

Total number of events matching the query window

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/metrics/events" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "firstAt": "2026-01-15T09:30:00Z",
  "lastAt": "2026-01-15T09:30:00Z",
  "topCity": "string",
  "topCountry": "string",
  "topDeviceType": "DEVICE_TYPE_DESKTOP",
  "totalCities": 0,
  "totalCountries": 0,
  "totalDeviceTypes": 0,
  "totalEvents": 0
}
```

### Response

200

`tokenCreditsLimit` integer (int32)

Monthly platform credits limit for the current cycle (0 means unlimited)

`tokenCreditsUsed` integer (int32)

Monthly platform credits consumed in the current cycle

`topupCreditsLimit` integer (int32)

Top-up credits total purchased (available = limit - used)

`topupCreditsUsed` integer (int32)

Top-up credits consumed (from purchased credit packs)

`totalDirectories` integer (int32)

Total number of directories (including subdirectories) in the workspace

`totalEvents` integer (int32)

Historical count of events generated by the workspace

`totalLinks` integer (int32)

Number of short links created within the workspace

`totalMembers` integer (int32)

Total number of active members in the workspace

`totalMonthlyEvents` integer (int32)

Events created within the current rolling month window

`totalPageThemeTemplates` integer (int32)

Number of page theme templates owned by the workspace

`totalQrcodeTemplates` integer (int32)

Number of QR code templates owned by the workspace

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/metrics/workspace" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "tokenCreditsLimit": 0,
  "tokenCreditsUsed": 0,
  "topupCreditsLimit": 0,
  "topupCreditsUsed": 0,
  "totalDirectories": 0,
  "totalEvents": 0,
  "totalLinks": 0,
  "totalMembers": 0,
  "totalMonthlyEvents": 0,
  "totalPageThemeTemplates": 0,
  "totalQrcodeTemplates": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

`key` string

`limit` integer (int32)

Maximum number of values (default 10)

`linkId` string

`startDate` string (date-time)

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

3 child attributes

`label` string

`percentage` number (double)

`visitorCount` integer (int32)

`total` integer (int32)

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/attributes/distribution" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "key": "string",
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "label": "string",
      "percentage": 0,
      "visitorCount": 0
    }
  ],
  "total": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`key` string

Attribute key, for example "rating"

`linkId` string

Optional link filter (UUID). Attributes belong to the visitor rather than to a link, so this filters the audience: visitors who interacted with the link, whatever set the attribute.

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`audienceCount` integer (int32)

Visitors in the audience, whether or not they have the attribute

`averageValue` number (double)

`coverageRate` number (double)

Share of the audience carrying the attribute, 0 to 1

`maxValue` number (double)

`minValue` number (double)

`totalCount` integer (int32)

Visitors carrying the attribute at all

`usableCount` integer (int32)

Values that parsed as numbers, so the denominator for averages. Lower than totalCount when some values do not match the attribute's declared type.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/attributes/metric" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "key": "string",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "audienceCount": 0,
  "averageValue": 0,
  "coverageRate": 0,
  "maxValue": 0,
  "minValue": 0,
  "totalCount": 0,
  "usableCount": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

`key` string

`limit` integer (int32)

Maximum number of values (default 50)

`linkId` string

`startDate` string (date-time)

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

2 child attributes

`recordedAt` string (date-time)

When the visitor last set it

`value` string

The value as captured

`total` integer (int32)

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/attributes/values" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "key": "string",
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "recordedAt": "2026-01-15T09:30:00Z",
      "value": "string"
    }
  ],
  "total": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`dimension` string

Dimension to break down by: "browser", "platform", "deviceType", "country", "city", "visitType", "inAppBrowser" (the app whose in-app browser opened the link; code holds the InAppBrowser value without its prefix, e.g. "INSTAGRAM", "NONE" for a regular browser) or "inAppBrowserVersion" (app and major version, e.g. "Instagram 447")

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`limit` integer (int32)

Maximum number of results (default 10)

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

Ordered list of dimension values by event count (descending)

4 child attributes

`code` string

Optional code (e.g. ISO 3166-1 alpha-2 country code for country dimension)

`eventCount` integer (int32)

Number of events for this dimension value

`label` string

Dimension label (e.g. browser name, country name, device type)

`percentage` number (double)

Percentage of total events

`total` integer (int32)

Total number of events in the date range

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/breakdown" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "dimension": "string",
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "code": "string",
      "eventCount": 0,
      "label": "string",
      "percentage": 0
    }
  ],
  "total": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

Device type breakdown

3 child attributes

`deviceType` string

Device type (e.g. "DESKTOP", "MOBILE", "TABLET")

`eventCount` integer (int32)

Number of events from this device type

`percentage` number (double)

Percentage of total events

`totalEvents` integer (int32)

Total number of events in the date range

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/devices" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "deviceType": "string",
      "eventCount": 0,
      "percentage": 0
    }
  ],
  "totalEvents": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`completionRate` number (double)

Conversion rate of the final step

`entryVisits` integer (int64)

Journeys that arrived; the denominator of every rate

`steps` array of object

Steps in the order a visitor meets them, arrival first

10 child attributes

`branches` array of object

Choices offered inside this step, where it offers one. A multi-link step is a single row but several different things happened in it.

3 child attributes

`label` string

The button's label, as the visitor saw it

`shareOfStep` number (double)

Visits as a percentage of the journeys that reached the step

`visits` integer (int64)

Journeys that took this branch. Zero means it was offered and nobody took it, which is worth seeing rather than hiding.

`conversionRate` number (double)

Visits as a percentage of those who arrived; the entry step is 100

`dropOffFromPrevious` integer (int64)

Journeys that did not get here from the step above

`identifiedVisitors` integer (int64)

How many of those journeys belong to a known visitor

`interactionRate` number (double)

Interactions as a percentage of occurrences.

The action is recorded on the trace the step already opened, so both counts come from the same rows and this cannot exceed 100, however many times one visitor pressed. Branch shares can add up past 100, which is a different and honest number: a social links page is not a fork, and one visitor may open every link on it.

`interactions` integer (int64)

Journeys where the visitor acted on the step rather than only reaching it: pressing a link on a social links page, choosing a button on a multi-link. Zero on steps that offer nothing to act on.

`occurrences` integer (int64)

Every trace recorded, so a step that repeats stays visible

`stepAction` string

Workflow step, e.g. "LINK\_VISIT", "FORM\_SUBMIT", "CLIENT\_REDIRECT"

`stepKind` string

"ENTRY", "CONDITION", "INTERACTION" or "EXIT"

`visits` integer (int64)

Journeys that reached this step, counted per event. Events are used rather than visitors because visitorId is NULL on most traces in practice, and counting visitors makes later steps look wider than the arrival they came from, which pushes conversion rates above 100%.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/funnel" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "completionRate": 0,
  "entryVisits": 0,
  "steps": [
    {
      "branches": [
        {
          "label": "string",
          "shareOfStep": 0,
          "visits": 0
        }
      ],
      "conversionRate": 0,
      "dropOffFromPrevious": 0,
      "identifiedVisitors": 0,
      "interactionRate": 0,
      "interactions": 0,
      "occurrences": 0,
      "stepAction": "string",
      "stepKind": "string",
      "visits": 0
    }
  ]
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`groupBy` string

Group by "country" or "city"

`limit` integer (int32)

Maximum number of results (default 10)

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

Ordered list of locations by event count (descending)

3 child attributes

`eventCount` integer (int32)

Number of events from this location

`location` string

Location name (country name or city name)

`percentage` number (double)

Percentage of total events

`totalEvents` integer (int32)

Total number of events in the date range

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/geo" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "groupBy": "string",
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "eventCount": 0,
      "location": "string",
      "percentage": 0
    }
  ],
  "totalEvents": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

2 child attributes

`eventCount` integer (int32)

Number of events in this hour across the date range

`hour` integer (int32)

Hour of day (0-23), on the clock of the time zone the response names

`timeZone` string

The workspace's time zone (IANA name) the hours are counted in

`totalEvents` integer (int32)

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/hours" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "eventCount": 0,
      "hour": 0
    }
  ],
  "timeZone": "string",
  "totalEvents": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

`groupBy` enum

Dimension to group by

Allowed values

* `GROUP_BY_DIMENSION_COUNTRY`
* `GROUP_BY_DIMENSION_CITY`
* `GROUP_BY_DIMENSION_DEVICE_TYPE`
* `GROUP_BY_DIMENSION_VISIT_TYPE`
* `GROUP_BY_DIMENSION_BROWSER`
* `GROUP_BY_DIMENSION_PLATFORM`
* `GROUP_BY_DIMENSION_IN_APP_BROWSER` The app whose in-app browser opened the link (Instagram, TikTok...), with visits in a regular browser as their own group
* `GROUP_BY_DIMENSION_IN_APP_BROWSER_VERSION` The in-app browser's app and major version ("Instagram 447")

`intervalInMinutes` integer (int32)

`limit` integer (int32)

Max number of groups to return (top N by volume). Default 5.

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`series` array of object

2 child attributes

`label` string

Series label (e.g. country name, device type, "new", "returning")

`points` array of object

Data points for this series

2 child attributes

`timestamp` string (date-time)

`value` integer (int32)

`totalEvents` integer (int32)

Total events across all series

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/timeseries" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "groupBy": "GROUP_BY_DIMENSION_COUNTRY",
  "intervalInMinutes": 0,
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "series": [
    {
      "label": "string",
      "points": [
        {
          "timestamp": "2026-01-15T09:30:00Z",
          "value": 0
        }
      ]
    }
  ],
  "totalEvents": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

`limit` integer (int32)

Max number of links to return (default 10)

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

3 child attributes

`eventCount` integer (int32)

Number of events for this link

`name` string

Link name or shortlink

`shortlink` string

Link shortlink identifier

`totalEvents` integer (int32)

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/top-links" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "limit": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "eventCount": 0,
      "name": "string",
      "shortlink": "string"
    }
  ],
  "totalEvents": 0
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`endDate` string (date-time)

Optional end; when omitted, counts up to now

`linkId` string

The link the split is on (UUID)

`startDate` string (date-time)

Optional start; when omitted, counts from the first visit

`stepId` string

The traffic split step (UUID)

### Response

200

`automatedVisitsExcluded` integer (int64)

Visits left out as bots, link previews or automated browsers

`enoughData` boolean

True once every variant with a weight above 0 has at least minimumVisitorsPerVariant visitors (visits when sticky is false). Below that, show "Not enough data yet".

`minimumVisitorsPerVariant` integer (int32)

The threshold behind enoughData

`sampleRatioMismatch` boolean

True when the real split is further from the configured weights than chance explains (chi-square test on visitors, or on visits when sticky is false, at p < 0.001, once each variant expects at least 100). Usually means the weights changed during the test or one path is broken; compare variants only after looking into it.

`sticky` boolean

The split's current sticky setting. When false, read the numbers as visits: one person may appear under more than one variant.

`totalVisitors` integer (int64)

Sum of the variants' visitors, bots and link previews left out. A device that changed variant counts under each.

`totalVisits` integer (int64)

Visits assigned, bots and link previews left out

`variants` array of object

The variants, in the step's order, then any since removed

7 child attributes

`label` string

The variant's label

`removed` boolean

True when the variant has since been removed from the step

`variantId` string

The variant's id

`visitorShare` number (double)

Share of the total in percent, to compare against weight: of visitors, or of visits when the split is not sticky

`visitors` integer (int64)

Distinct devices assigned to this variant, bots and link previews left out

`visits` integer (int64)

Visits assigned to this variant, bots and link previews left out. A returning visitor counts once per visit.

`weight` integer (int32)

Its configured weight, in percent; 0 for a variant no longer on the step

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/traffic-split" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "endDate": "2026-01-15T09:30:00Z",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "stepId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f"
}'
```

Response 200

```json
{
  "automatedVisitsExcluded": 0,
  "enoughData": false,
  "minimumVisitorsPerVariant": 0,
  "sampleRatioMismatch": false,
  "sticky": false,
  "totalVisitors": 0,
  "totalVisits": 0,
  "variants": [
    {
      "label": "string",
      "removed": false,
      "variantId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "visitorShare": 0,
      "visitors": 0,
      "visits": 0,
      "weight": 0
    }
  ]
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`countries` array of string

Optional country filter: visits from any of these countries (ISO 3166-1 alpha-2 codes, e.g. "FR"). Combines with the link, directory or tag filter

`directoryId` string

Optional directory filter (UUID): the links of this directory and of every directory below it. Send linkId or directoryId, not both; when both are omitted aggregates workspace-wide

`endDate` string (date-time)

Inclusive end timestamp

`intervalInMinutes` integer (int32)

Bucket size in minutes (e.g. 60 for hourly, 1440 for daily)

`linkId` string

Optional link filter (UUID); when omitted aggregates workspace-wide

`startDate` string (date-time)

Inclusive start timestamp

`tagId` string

Optional tag filter (UUID): every link carrying this tag. Send at most one of linkId, directoryId and tagId

### Response

200

`data` array of object

Time-bucketed visitor trend data

3 child attributes

`newVisitorCount` integer (int32)

Number of first-time visitors in this interval

`returningVisitorCount` integer (int32)

Number of returning visitors in this interval

`timestamp` string (date-time)

Start timestamp of the interval

`totalNew` integer (int32)

Total new visitors in the range

`totalReturning` integer (int32)

Total returning visitors in the range

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/visitors" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "countries": [
    "FR",
    "BE"
  ],
  "directoryId": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "endDate": "2026-01-15T09:30:00Z",
  "intervalInMinutes": 0,
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "startDate": "2026-01-15T09:30:00Z",
  "tagId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}'
```

Response 200

```json
{
  "data": [
    {
      "newVisitorCount": 0,
      "returningVisitorCount": 0,
      "timestamp": "2026-01-15T09:30:00Z"
    }
  ],
  "totalNew": 0,
  "totalReturning": 0
}
```

---

Source: https://linkbreakers.com/help/api/analytics
