Analytics
Read analytics for the active product from the terminal. Analytics commands are read-only and require a token or API key with theanalytics:read scope.
Analytics commands require
--scope <org-slug>/<product-slug>.Performance reports
Generate the same PDF as the admin-mode report generator. The CLI command is available to admins and non-admins with access to the product.
All visibility metrics use the selected date range, not rolling 30-day snapshots.
SoV change is in percentage points against the preceding equal-length period.
AI traffic includes inference visits only. The PDF shows the industry leader and
nearby ranks, share of voice for up to five models, and up to six topics
representing winning, contested, and opportunity states. Model bars show each
model’s share of voice, not a normalized split that adds up to 100%. JSON contains
the full ranking, model, and topic data.
Topic labels follow the dashboard: winning means the product ranks first;
contested means another product leads but this product is ranked; opportunity
means the topic has a leader but this product is unranked. Topics without a leader
are labeled unranked. Successful empty visibility queries show
0.0%, including
topic rows. Failed sections are marked unavailable, not zero. A partial report
still downloads and lists unavailable sections.
Version 2 uses one US Letter page (8.5 × 11 inches):
- Share of voice: selected-period SoV and its preceding-period change. Recommendation rate is optional and off by default. When shown, it includes unconditional and conditional recommendations among completed answers. It is unavailable when there are no answers or classification is incomplete.
- Models: four models ranked by SoV, with short inline bars on a shared 0–100% scale.
- Industry ranking: ranks #1 and #2, your standing, the rank directly above you, and up to five pinned competitors. Duplicate products appear once. Pinned competitors without observations show no rank, rather than an invented standing. The most recently pinned competitors are selected when there are more than five.
- Citation coverage: the percentage and X/Total of currently tracked pages cited during the period. Citations at a linked page’s archived URL credit its current tracked URL. The five most-cited tracked pages show stored titles, with page paths as a fallback. This is page coverage, not the fraction of answers containing a citation. No tracked pages yields 0.0% and 0/0. Failed analytics are unavailable, not zero.
- Topics: the three highest-SoV winning topics and three lowest-SoV losing topics. Winning means the product leads; losing includes contested and opportunity topics. Topics without a leader are not classified as winning or losing.
- Perception: up to three positive and three negative perceptions, ranked by answer count. It is on by default and can be hidden.
v2; version 2 filenames include -v2. For backward compatibility, the API still defaults to version 1 when version is omitted. UI and CLI explicitly request version 2.
Share of voice
tpc analytics sov returns one value for the selected date range. It counts
completed runs that mention the product, divides by all completed runs in the
same scope and range, and then multiplies by 100. The default range includes
today and the preceding 29 calendar days.
--timeseries, --by, --prompt, and --topic return rolling snapshots. In
those modes, --from, --to, and --last select snapshot dates. For a
product or --by engine request, --granularity day|week|month selects the UTC
calendar bucket and --rolling-window 1..30 controls how many buckets are
included in each point. They default to day and 30. Adjacent snapshots
overlap, so do not sum their mentions or runs values.
Perceptions
tpc analytics perceptions returns the data on the Answer Analytics Sentiment
card. It prints the positive, neutral, and negative split overall and per answer
engine. Then it lists each perception label with its sentiment, mention count,
the answer engines that said it, the date it was last seen, and a sample quote.
The most frequent labels come first.
The sentiment split always covers the whole timeframe.
--sentiment and
--search filter only the perception list. --format csv writes only the
perception list.
To read the answers behind one perception, pass its label and sentiment exactly
as tpc analytics perceptions prints them:
answers takes the same --timeframe, --page, and --page-size flags.
Explore: build your own analytics query
tpc analytics explore is the flexible query surface behind the fixed commands above. Pick one metric, group it by at most one value with --by, then scope it with filters and a date window. It calls the POST /api/v1/analytics/explore endpoint, so anything you can do here you can also do from the API or the explore_analytics MCP tool.
--last 7d|30d|90d, or --from and --to together to select a range. The flexible explore SoV query retains snapshot semantics: omitting --by returns only the latest available rolling snapshot, while --by date returns one overlapping rolling snapshot per date. --granularity day|week|month selects the UTC bucket and --rolling-window 1..30 controls how many buckets each SOV snapshot contains; they default to day and 30. Custom settings work for product, date, and engine SOV series. SoV mentions and runs from explore are not start-to-end totals, so you must not sum them across dated rows. Use the fixed tpc analytics sov command when you need one accumulated date-range value.
The response is a generic table: the API returns column metadata alongside flat rows, so every metric renders the same way. Add --json to get the machine-readable response for scripting:
tpc analytics explore --help for the full flag reference.