Usage totals

The five AI figures for a window, as one object.

GET/sites/{siteId}/ai/usage

Usage totals

curl --request GET \
  --url 'https://truestat.io/api/v1/sites/{siteId}/ai/usage' \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "llm_exports": 0,
    "ai_referrals": 9,
    "crawler_views": 8706,
    "assistant_opens": 0,
    "assistant_messages": 0
  },
  "meta": {
    "range": {
      "to": "2026-09-16T13:40:00.000Z",
      "tz": "UTC",
      "from": "2026-09-09T13:40:00.000Z",
      "clamped": false
    },
    "site_id": "6fed8980-a119-4a9c-a4d4-53e448ef9f9e"
  }
}

One object, five numbers — what the AI panel puts across its top.

Call this when you want the headline figures. The other five /ai/* endpoints break each of them down.

What each number counts

Field	Counts
`crawler_views`	Every request from a recognised crawler, whatever it came for. Break it down with crawlers.
`llm_exports`	Fetches of the machine-readable files you publish.
`assistant_opens`	Sessions that began inside an assistant's own browser.
`assistant_messages`	Messages exchanged in those sessions.
`ai_referrals`	People who arrived from an assistant's answer. Break it down with referrals.

`llm_exports` is the one you control

The other four measure what the world did to your site. This one measures whether a thing you published was found.

llms.txt and its siblings are files you write for machines — a plain-text map of what your site contains and how you want it described. Publishing one is a few minutes of work; knowing whether anything ever fetched it is what turns it from a hopeful gesture into something you can decide about.

A zero here is a real answer: either nothing has looked yet, or the file is not where crawlers expect it. What this panel shows covers the file itself.

Zeroes are common and usually correct

assistant_opens and assistant_messages only fill in when somebody browses your site from inside an assistant's own browser, which is a narrow and fairly new behaviour. On most sites they are zero, and that is a measurement rather than a gap.

The same is not true of crawler_views. A zero there means no recognised crawler reached the site in the window — worth checking against how reliable is it before drawing a conclusion.

These numbers do not reconcile with `/overview`

/overview counts people, with crawlers excluded by default. Four of the five figures here count machines. The one that overlaps is ai_referrals — those are ordinary visitors and they are inside your overview totals too.

Crawler traffic is always counted here, whatever bots says. See crawlers.

Authorizations

Authorizationstringheaderrequired

An API key from Settings → API keys. Scopes available: analytics:read, sites:read, sites:write, settings:read, settings:write, goals:read, goals:write, funnels:read, funnels:write, notes:read, notes:write, alerts:read, alerts:write, team:read, team:write, revenue:read, revenue:write.

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path parameters

siteIdstring (uuid)pathrequired

The site's id, from `GET /sites`. A site that is not yours and a site that does not exist both answer 403, so this cannot be used to discover other people's ids.

Query parameters

periodenum<string>query

A named window, resolved in `tz`. Cannot be combined with `from`/`to` — a request carrying both is refused rather than guessed at.

options:todayyesterdaylast24hlast7dlast30dlast12mmonthyearall

fromstring (date-time)query

Start of the window, ISO 8601 with an offset. Must be given together with `to`.

tostring (date-time)query

End of the window. Must be given together with `from`.

tzstringquerydefault: UTC

IANA timezone for day boundaries. `period=today&tz=Europe/Istanbul` means the reader's today, not the server's. Defaults to UTC.

botsenum<string>querydefault: excluded

Whether crawler traffic is counted. Excluded by default — the `/ai/*` endpoints report it separately and always include it.

options:excludedincluded

filter_pathstringquery

Narrow the result to one `path`.

filter_path_patternstringquery

Narrow the result to one `path_pattern`.

filter_hostnamestringquery

Narrow the result to one `hostname`.

filter_entry_pathstringquery

Narrow the result to one `entry_path`.

filter_exit_linkstringquery

Narrow the result to one `exit_link`.

filter_file_downloadstringquery

Narrow the result to one `file_download`.

filter_goalstringquery

Narrow the result to one `goal`.

filter_browserstringquery

Narrow the result to one `browser`.

filter_osstringquery

Narrow the result to one `os`.

filter_devicestringquery

Narrow the result to one `device`.

filter_countrystringquery

Narrow the result to one `country`.

filter_regionstringquery

Narrow the result to one `region`.

filter_citystringquery

Narrow the result to one `city`.

filter_referrerstringquery

Narrow the result to one `referrer`.

filter_channelstringquery

Narrow the result to one `channel`.

filter_utm_sourcestringquery

Narrow the result to one `utm_source`.

filter_utm_mediumstringquery

Narrow the result to one `utm_medium`.

filter_utm_campaignstringquery

Narrow the result to one `utm_campaign`.

filter_gad_campaign_idstringquery

Narrow the result to one `gad_campaign_id`.

filter_utm_termstringquery

Narrow the result to one `utm_term`.

filter_bot_kindstringquery

Narrow the result to one `bot_kind`.

Response

application/json

The answer.

dataobject

metaobject

errorobject