> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptingcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Read share of voice, sentiment, traffic, and citations from the TPC CLI, or build a custom query with explore.

# Analytics

Read analytics for the active product from the terminal. Analytics commands are read-only and require a token or API key with the `analytics:read` scope.

<Note>
  Run `tpc product switch <product-slug>` first — every analytics command is scoped to the active product.
</Note>

```bash theme={null}
# Product share of voice over the last 30 days
tpc analytics sov

# Industry ranking (competitor share of voice)
tpc analytics sov --by competitor

# Per-prompt sentiment with week-over-week change
tpc analytics sentiment --wow

# AI traffic grouped by page
tpc analytics traffic --by page

# Cited sources leaderboard
tpc analytics citations --last 30d --top 25
```

## 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 `exploreAnalytics` MCP tool.

| Metric      | Group by (`--by`)                                       | Filters                                                                                                                  |
| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `sov`       | `date`, `prompt`, `topic`, `engine`, `competitor`       | `--view`, `--prompt`, `--topic`, `--engine`, `--region`                                                                  |
| `citations` | `source`, `category`, `type`, `author`, `model`, `date` | `--view`, `--topic`, `--region`, `--category`, `--content-type`, `--model`, `--author`, `--query`, `--product-mentioned` |
| `traffic`   | `date`, `page`, `model`, `category`                     | `--traffic-type`, `--provider`, `--category`                                                                             |
| `sentiment` | `prompt`                                                | `--view`, `--prompt`, `--topic`                                                                                          |

```bash theme={null}
# Product share of voice summary
tpc analytics explore --metric sov

# Industry ranking: every competitor's share of voice, ranked
tpc analytics explore --metric sov --by competitor --last 30d

# Industry ranking within one topic (category ranking)
tpc analytics explore --metric sov --by competitor --topic <topicId>

# Share-of-voice time series for one prompt
tpc analytics explore --metric sov --by date --prompt <promptId>

# Citations grouped by source category over the last 90 days
tpc analytics explore --metric citations --by category --last 90d

# Top cited sources sorted by unique conversations
tpc analytics explore --metric citations --by source --sort-by mentions --top 25

# Weekly AI traffic buckets
tpc analytics explore --metric traffic --by date --bucket week

# Human traffic by page
tpc analytics explore --metric traffic --by page --traffic-type human

# Sentiment per prompt with week-over-week comparison
tpc analytics explore --metric sentiment --compare wow
```

Date windows default to the last 30 days. Use `--last 7d|30d|90d`, or `--from` and `--to` together for an exact range.

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:

```bash theme={null}
# Top three competitors as JSON rows
tpc analytics explore --metric sov --by competitor --top 3 --json | jq '.rows'
```

Filters that do not apply to the chosen metric are rejected with the supported list, so agents and scripts get a correcting error instead of silently wrong data. See `tpc analytics explore --help` for the full flag reference.