MCP tools

How the tools are named

Every tool is traceten_<resource>_<action> and maps one to one onto a documented REST endpoint, with the same arguments, the same validation and the same permissions. Anything you can do through a tool you can do with curl, and the reverse. Your assistant sees a full description of each tool, including the traps that change the answer. This page is the map.

Reading the table

Permission is the API key permission the call needs. A key without it gets a clear error naming what is missing, rather than a silent empty result.
(confirm) marks a tool that returns a preview and changes nothing until you approve it. See Safety and permissions.
traceten_sites_create needs three permissions because it mints a key, and a key can never create one more capable than itself. stats:read and ingest:write are what the new key will carry, so the caller has to hold them already. This is not a reason to over-provision your other keys.
Every site-scoped tool takes site_id (or siteId) as the ttid_ snippet key from traceten_sites_list, not the UUID in your dashboard URL.

Two distinctions worth knowing before you read a number

ai_source is not source_kind. ai_source names which assistant sent the traffic (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok). source_kind names the category of traffic (ai, non_ai, unknown, and on the revenue side a fourth value, unmatched). They are different axes over overlapping populations. Adding a figure from one to a figure from the other double counts. A session is not a person. A session is one visit, and it ends after 30 minutes of inactivity. A returning customer is many sessions and one visitor, so a session count is never a headcount.

The tools

Stats

Tool	What it answers	Endpoint	Permission
`traceten_stats_overview`	Headline numbers for a window	`GET /v1/stats/overview`	`stats:read`
`traceten_stats_timeseries`	Headline numbers, bucketed over time	`GET /v1/stats/timeseries`	`stats:read`
`traceten_stats_realtime`	Who is on the site right now	`GET /v1/stats/realtime`	`stats:read`
`traceten_stats_metadata`	A site’s display settings	`GET /v1/stats/metadata`	`stats:read`

AI attribution

Tool	What it answers	Endpoint	Permission
`traceten_breakdown_ai_sources`	Which AI assistants sent traffic, and what it was worth	`GET /v1/breakdowns/ai-sources`	`stats:read`
`traceten_breakdown_source_kinds`	AI vs non-AI vs unknown traffic	`GET /v1/breakdowns/source-kinds`	`stats:read`
`traceten_detection_quality`	What the bot filter removed	`GET /v1/detection/quality`	`stats:read`
`traceten_detection_coverage`	How much revenue could be tied to a session	`GET /v1/detection/coverage`	`stats:read`

AI crawlers

Tool	What it answers	Endpoint	Permission
`traceten_ai_crawls_summary`	AI crawler totals and how far they were verified	`GET /v1/ai-crawls/summary`	`stats:read`
`traceten_ai_crawls_by_page`	Which pages AI crawlers read	`GET /v1/ai-crawls/by-page`	`stats:read`
`traceten_ai_crawls_timeline`	Daily AI crawl volume	`GET /v1/ai-crawls/timeline`	`stats:read`
`traceten_ai_crawls_series`	Ranked daily crawl series by company or page	`GET /v1/ai-crawls/series`	`stats:read`
`traceten_ai_crawls_recent`	The live AI crawler feed	`GET /v1/ai-crawls/recent`	`stats:read`

Answer-engine visibility

Tool	What it answers	Endpoint	Permission
`traceten_visibility_summary`	Do answer engines mention and cite this brand	`GET /v1/visibility/summary`	`stats:read`
`traceten_visibility_timeseries`	Visibility over time, by scan window	`GET /v1/visibility/timeseries`	`stats:read`
`traceten_visibility_competitors`	Share of voice against tracked competitors	`GET /v1/visibility/competitors`	`stats:read`
`traceten_visibility_by_prompt`	Per-prompt presence, rivals and cited pages	`GET /v1/visibility/by-prompt`	`stats:read`
`traceten_citations_by_page`	Cited pages, joined to crawls and revenue	`GET /v1/visibility/citations/by-page`	`stats:read`
`traceten_visibility_runs`	The verbatim answers behind the numbers	`GET /v1/visibility/runs`	`stats:read`

traceten_visibility_runs returns answer text written by third-party AI engines. That text can name people and companies other than you. It carries no visitor identifier and describes nobody who visited your site, but it is the one visibility tool whose output is prose rather than counts. See Safety and permissions.

What gets measured

These tools change the measurement itself, not just settings. The prompt list is the denominator of every rate in the table above: adding a question you rank badly for lowers your presence rate, and removing one raises it, without anything changing on your site.

Tool	What it answers	Endpoint	Permission
`traceten_brands_list`	Which brands are matched in answers	`GET /v1/visibility/brands`	`stats:read`
`traceten_brands_create`	Track a brand or a competitor	`POST /v1/visibility/brands`	`config:write`
`traceten_brands_update`	Change a brand’s name, aliases or domains	`PATCH /v1/visibility/brands/{id}`	`config:write`
`traceten_brands_confirm`	Admit a proposed brand to measurement	`POST /v1/visibility/brands/{id}/confirm`	`config:write`
`traceten_brands_archive` (confirm)	Stop tracking a brand	`DELETE /v1/visibility/brands/{id}`	`config:write`
`traceten_prompts_list`	Which questions the engines are asked	`GET /v1/visibility/prompts`	`stats:read`
`traceten_prompts_create`	Track a question	`POST /v1/visibility/prompts`	`config:write`
`traceten_prompts_update`	Change a question’s grouping or status	`PATCH /v1/visibility/prompts/{id}`	`config:write`
`traceten_prompts_replace`	Reword a question (archives the old one)	`POST /v1/visibility/prompts/{id}/replace`	`config:write`
`traceten_prompts_archive` (confirm)	Stop asking a question	`DELETE /v1/visibility/prompts/{id}`	`config:write`
`traceten_prompts_suggest`	Suggest questions from your own pages	`POST /v1/visibility/prompts/suggest`	`config:write`

Three things worth knowing before you let an assistant use these:

A prompt’s wording can never be edited. Past runs record only the prompt’s id, so changing the text would rewrite what your history claims was asked. traceten_prompts_replace archives the old question and returns a new one with a new id, starting a new series.
Suggestions are never enrolled automatically. traceten_prompts_suggest returns candidates and saves nothing. You create the ones you want. The prompt list decides your score, so Traceten does not get to pick it.
traceten_prompts_suggest needs config:write even though it saves nothing, because it makes Traceten fetch your site: at most 8 pages, 12 requests and 15 seconds, every request pinned to your own host, honouring your robots.txt. Your site must already have received tracking events, or it returns 409 site_not_verified and fetches nothing. No AI provider is involved; the candidates are templates filled with your own page wording, copied verbatim, so read them before you create them.

Revenue

Tool	What it answers	Endpoint	Permission
`traceten_revenue_breakdown`	Attributed revenue by source	`GET /v1/revenue/breakdown`	`stats:read`
`traceten_revenue_timeseries`	Attributed revenue over time	`GET /v1/revenue/timeseries`	`stats:read`
`traceten_revenue_sku_breakdown`	Revenue by product and SKU	`GET /v1/revenue/sku-breakdown`	`stats:read`
`traceten_revenue_ltv`	Lifetime value by acquisition source	`GET /v1/revenue/ltv`	`stats:read`

Breakdowns

Tool	What it answers	Endpoint	Permission
`traceten_breakdown_pages`	Top pages	`GET /v1/breakdowns/pages`	`stats:read`
`traceten_breakdown_referrers`	Traffic sources by name	`GET /v1/breakdowns/referrers`	`stats:read`
`traceten_breakdown_countries`	Sessions by country	`GET /v1/breakdowns/countries`	`stats:read`
`traceten_breakdown_cities`	Sessions by city	`GET /v1/breakdowns/cities`	`stats:read`
`traceten_breakdown_devices`	Sessions by device type	`GET /v1/breakdowns/devices`	`stats:read`
`traceten_breakdown_browsers`	Sessions by browser	`GET /v1/breakdowns/browsers`	`stats:read`
`traceten_breakdown_operating_systems`	Sessions by operating system	`GET /v1/breakdowns/operating-systems`	`stats:read`
`traceten_breakdown_campaigns`	Sessions by utm_campaign	`GET /v1/breakdowns/campaigns`	`stats:read`
`traceten_breakdown_hostnames`	Sessions by hostname	`GET /v1/breakdowns/hostnames`	`stats:read`
`traceten_breakdown_exit_links`	Sessions by outbound link domain	`GET /v1/breakdowns/exit-links`	`stats:read`

Sessions

Tool	What it answers	Endpoint	Permission
`traceten_sessions_list`	List sessions with their AI attribution	`GET /v1/sessions`	`stats:read`
`traceten_sessions_get`	One session in full	`GET /v1/sessions/{id}/detail`	`stats:read`
`traceten_sessions_journey`	Multi-touch AI attribution for one session	`GET /v1/sessions/{id}/journey`	`stats:read`

For what a visit actually did, and for the person behind it, go through the Visitors tools. traceten_visitors_timeline returns the events inside each of a person’s visits, and traceten_visitors_get returns the person.

Goals

Tool	What it answers	Endpoint	Permission
`traceten_goals_list`	List a site’s goals	`GET /v1/goals`	`stats:read`
`traceten_goals_create`	Pre-declare a goal	`POST /v1/goals`	`config:write`
`traceten_goals_update`	Rename a goal’s display fields	`PATCH /v1/goals/{id}`	`config:write`
`traceten_goals_archive` (confirm)	Archive a goal	`DELETE /v1/goals/{id}`	`config:write`
`traceten_goals_unarchive`	Restore an archived goal	`POST /v1/goals/{id}/unarchive`	`config:write`
`traceten_goals_timeseries`	Goal completions per day	`GET /v1/goals/timeseries`	`stats:read`
`traceten_goals_properties`	Property breakdown for one goal	`GET /v1/goals/{name}/properties`	`stats:read`

Funnels

Tool	What it answers	Endpoint	Permission
`traceten_funnels_list`	List a site’s funnels	`GET /v1/funnels`	`stats:read`
`traceten_funnels_create`	Define a funnel	`POST /v1/funnels`	`config:write`
`traceten_funnels_update`	Edit a funnel definition	`PATCH /v1/funnels/{id}`	`config:write`
`traceten_funnels_delete` (confirm)	Delete a funnel	`DELETE /v1/funnels/{id}`	`config:write`
`traceten_funnels_results`	Run a funnel	`GET /v1/funnels/{id}/results`	`stats:read`

Visitors

One row per person rather than per visit. Use these when the question counts people, and the Sessions tools when it counts visits.

Tool	What it answers	Endpoint	Permission
`traceten_visitors_list`	List visitors, filtered and sorted	`GET /v1/visitors`	`stats:read`
`traceten_visitors_get`	One visitor in full	`GET /v1/visitors/{handle}`	`stats:read`
`traceten_visitors_timeline`	What one visitor did, visit by visit	`GET /v1/visitors/{handle}/timeline`	`stats:read`
`traceten_funnels_step_visitors`	Who dropped at one funnel step	`GET /v1/funnels/{id}/steps/{position}/visitors`	`stats:read`
`traceten_goals_visitors`	Who completed one goal	`GET /v1/goals/{name}/visitors`	`stats:read`

traceten_visitors_timeline pages by visit, not by event: page_size counts visits and one page of 10 can carry several hundred events. It returns two date ranges, and they are different. meta.effective_window is the range you asked for, clamped to how long a session record is kept. history_window is the range the visits are drawn from, bounded by how long raw events are kept, and it is usually wider. Rows carry an opaque handle, not a visitor identifier. A handle is stable, so an assistant can cache it and come back to it, and it is scoped to one site, so the same person on another of your sites has a different one and this one returns 404 there. It is not reversible by you and carries no name, email address or IP address.

Chart notes

Notes your team pins to UTC days on a site’s traffic chart. They are shared with everyone in the organization. Note text is written by people, so the tools return it wrapped as { "untrusted_text": … }, and your assistant is told to treat it as data, never as instructions. The assistant’s vendor receives the text it reads. Member ids are never returned; created_via says whether a note came from the dashboard, an API key or an AI assistant.

Tool	What it answers	Endpoint	Permission
`traceten_annotations_list`	List a site’s chart notes	`GET /v1/annotations`	`stats:read`
`traceten_annotations_create`	Add a chart note	`POST /v1/annotations`	`config:write`
`traceten_annotations_update` (confirm)	Change a chart note	`PATCH /v1/annotations/{id}`	`config:write`
`traceten_annotations_delete` (confirm)	Delete a chart note	`DELETE /v1/annotations/{id}`	`config:write`

Sites

Tool	What it answers	Endpoint	Permission
`traceten_sites_list`	List the account’s sites	`GET /v1/sites`	`stats:read`
`traceten_sites_get`	Fetch one site	`GET /v1/sites/{siteId}`	`stats:read`
`traceten_sites_create` (confirm)	Create a site	`POST /v1/sites`	`credentials:write` + `stats:read` + `ingest:write`
`traceten_sites_update` (confirm)	Update a site’s settings	`PATCH /v1/sites/{siteId}`	`config:write`

Account and keys

Tool	What it answers	Endpoint	Permission
`traceten_account_get`	The account’s profile and plan	`GET /v1/account`	`stats:read`
`traceten_account_usage`	Current billing period consumption	`GET /v1/account/usage`	`stats:read`
`traceten_apikeys_list`	List the account’s API keys	`GET /v1/account/api-keys`	`config:write`
`traceten_apikeys_create` (confirm)	Mint an API key	`POST /v1/account/api-keys`	`credentials:write`
`traceten_apikeys_revoke` (confirm)	Revoke an API key	`DELETE /v1/account/api-keys/{keyId}`	`config:write`

Webhooks

Tool	What it answers	Endpoint	Permission
`traceten_webhooks_list`	List a site’s outbound webhooks	`GET /v1/sites/{siteId}/webhooks`	`stats:read`
`traceten_webhooks_create` (confirm)	Register an outbound webhook	`POST /v1/sites/{siteId}/webhooks`	`credentials:write`
`traceten_webhooks_test`	Send a test ping	`POST /v1/sites/{siteId}/webhooks/{webhookId}/test`	`config:write`
`traceten_webhooks_rotate_secret` (confirm)	Rotate a webhook’s signing secret	`POST /v1/sites/{siteId}/webhooks/{webhookId}/rotate-secret`	`credentials:write`

Integrations and team

Tool	What it answers	Endpoint	Permission
`traceten_integrations_status`	Revenue provider connection status	`GET /v1/integrations`	`stats:read`
`traceten_team_list`	The account’s members and their roles	`GET /v1/team`	`stats:read`

Tools that deliberately do not exist

No lookup by identity. traceten_visitors_list filters people by dimensions you already report on: source, campaign, landing page, country, city, device, browser. No tool accepts a name, an email address, an IP address or a visitor identifier as an input, because none of those is stored in a form any tool could match. A handle addresses a visitor an assistant has already listed; it is not a search term.
No cross-site view of a person. Every tool is scoped to one site, and a handle from one site means nothing on another. Traceten holds no key that links a person’s activity across two customers.
No event write or delete. Recording events belongs to the server SDKs; erasure belongs to the data deletion API, which needs its own permission.
No site deletion. Deleting a property destroys its history. That stays in the dashboard, behind a typed confirmation.
No integration connect or disconnect. Connecting pastes a secret and follows a browser redirect, neither of which an assistant can do safely.
No team changes. Membership and roles live in your identity provider.
No regions breakdown. Traceten records country and city, and holds no region field, so there is nothing to report.

Safety and permissions
API reference for the same surface over HTTP

MCP server

How the tools are named

Reading the table

Two distinctions worth knowing before you read a number

The tools

Stats

AI attribution

AI crawlers

Answer-engine visibility

What gets measured

Revenue

Breakdowns

Sessions

Goals

Funnels

Visitors

Chart notes

Sites

Account and keys

Webhooks

Integrations and team

Tools that deliberately do not exist

Next

​How the tools are named

​Reading the table

​Two distinctions worth knowing before you read a number

​The tools

​Stats

​AI attribution

​AI crawlers

​Answer-engine visibility

​What gets measured

​Revenue

​Breakdowns

​Sessions

​Goals

​Funnels

​Visitors

​Chart notes

​Sites

​Account and keys

​Webhooks

​Integrations and team

​Tools that deliberately do not exist

​Next

How the tools are named

Reading the table

Two distinctions worth knowing before you read a number

The tools

Stats

AI attribution

AI crawlers

Answer-engine visibility

What gets measured

Revenue

Breakdowns

Sessions

Goals

Funnels

Visitors

Chart notes

Sites

Account and keys

Webhooks

Integrations and team

Tools that deliberately do not exist

Next