Endpoint reference

Not available yet. These routes are designed and the queries behind them are built; the routes themselves are not. This page describes the planned surface. When it ships, this reference is generated from the same schemas the API validates against, so it cannot drift from the implementation.

Base URL: https://truestat.io/api/v1/

All endpoints are GET. All are read-only. All need an API key on the Pro tier.

The endpoints

Which one to call

/overview for a single number on a status page. It is one query.

/summary for a full dashboard rebuild. It fans out across every breakdown, so it is a much heavier call — do not poll it every 30 seconds for one figure.

/timeseries and /breakdowns/{dimension} for anything in between.

Breakdown dimensions

pages · referrers · channels · campaigns · keywords · countries · regions · cities · browsers · os · devices

channels and keywords have no equivalent in comparable products.

One-site keys

If a key is scoped to exactly one site, the {id} segment can be omitted — /api/v1/summary resolves to that site. It is a convenience only; the same authorisation runs either way.

Shared parameters

Apply to /overview, /timeseries, /breakdowns/*, /summary and both /ai/* endpoints.

Filters

Flat query parameters, one per dimension:

filter_path          filter_path_pattern   filter_browser
filter_os            filter_device         filter_country
filter_region        filter_city           filter_referrer
filter_channel       filter_utm_source     filter_utm_medium
filter_utm_campaign  filter_utm_term       filter_bot_kind

Equality only. There is no is_not, no contains and no numeric comparison. The one exception is filter_path_pattern, which accepts * as a wildcard:

?filter_path_pattern=/blog/*

filter_bot_kind applies to the /ai/* endpoints and takes ai_assistant, ai_training, search or other.

Retention clamping

If your range reaches further back than your tier's retention window, you get the data that exists and the response says so — not an error, and not a silent truncation:

"meta": { "range": { "clamped": true, "from": "2023-08-24T00:00:00Z" } }

Retention is 3 years on Starter and 5 on Pro, and the API reads the same window the dashboard does. See Data retention.

The response envelope

One shape, on every endpoint, with no exceptions:

{
  "data": { },
  "meta": {
    "site_id": "…",
    "range": { "from": "…", "to": "…", "tz": "UTC", "clamped": false },
    "unit": "day",
    "bots": "excluded",
    "pagination": { "limit": 100, "offset": 0 }
  }
}

Errors use one shape too, with a symbolic code rather than a repeated HTTP status:

{ "error": { "code": "insufficient_scope", "message": "…" } }

error.message never contains anything from your request. See Errors.

Adding a field to data is not a breaking change. Read the fields you need and ignore the rest.

Pagination

limit and offset on breakdowns. There is no cursor.

meta.pagination carries limit and offset and not a total, because the underlying queries do not compute one. Rather than fabricate a number, it is absent. To tell whether more rows exist, ask for one more than you need.

What is not here, and will not be

What is deferred, not refused