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

# Analytics

> Read Tool Use data from the terminal — terminal commands and MCP tool calls

`unbound analytics tool-use` reads the Analytics → Tool Use tables from the terminal: what agents ran, which MCP tools they called, and which policies matched.

Requires **Admin** role. Run `unbound status` to check.

## Datasets

| Dataset        | What it holds                                                                 |
| -------------- | ----------------------------------------------------------------------------- |
| `terminal`     | Terminal commands agents ran, with risk score and matched tool policies       |
| `mcp-actions`  | Individual MCP tool calls, with server, tool, targets and risk score          |
| `unsanctioned` | MCP calls to servers your organization has not sanctioned (blocked or warned) |
| `mcp-servers`  | One row per MCP server: action count and average risk                         |

```bash theme={null}
unbound analytics tool-use terminal
unbound analytics tool-use mcp-actions --server claude_ai_notion
unbound analytics tool-use unsanctioned --time-window THIRTY_DAYS
unbound analytics tool-use mcp-servers
```

Run `mcp-servers` first when you need a value for `--server` — it lists the names the other datasets accept.

## Filters

All of these take comma-separated values and work on every dataset unless noted.

| Flag                  | Filters by                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--time-window <w>`   | `ONE_DAY`, `THREE_DAYS`, `SEVEN_DAYS`, `FOURTEEN_DAYS`, `THIRTY_DAYS`, `THREE_MONTHS`. Default `THIRTY_DAYS` |
| `--start`, `--end`    | A custom range as `YYYY-MM-DD`, up to 90 days. Not combined with `--time-window`                             |
| `--tool <types>`      | AI tool, e.g. `CLAUDE_CODE,CURSOR,CODEX`                                                                     |
| `--user <ids>`        | User IDs (see `unbound users list`)                                                                          |
| `--risk <levels>`     | `Low`, `Medium`, `High`                                                                                      |
| `--policy <ids>`      | Tool policy IDs (see `unbound policy tool list`)                                                             |
| `--family <families>` | Command family — `terminal` only                                                                             |
| `--server <names>`    | MCP server or service name — MCP datasets only                                                               |
| `--initiator <who>`   | `user`, `agent`, or `unknown`                                                                                |

```bash theme={null}
unbound analytics tool-use terminal --risk High --time-window SEVEN_DAYS
unbound analytics tool-use terminal --family git_action,delete_file --initiator agent
unbound analytics tool-use terminal --start 2026-07-01 --end 2026-07-31
```

## Output

The default is a table sized to your terminal, showing a curated set of columns.

| Flag                  | Behavior                                                            |
| --------------------- | ------------------------------------------------------------------- |
| `--format <f>`        | `table` (default), `json`, or `csv`                                 |
| `--json`              | Shorthand for `--format json`                                       |
| `--wide`              | Print full values instead of clipping to the terminal width         |
| `--limit <n>`         | Rows to show — default 20, up to 100 for a table and 1,000 for JSON |
| `--offset <n>`        | Skip n rows, for paging                                             |
| `-o, --output <file>` | Write to a file instead of stdout — `json` and `csv` only           |

The table hides the widest columns to stay readable. Use `--wide`, or `--format json`, to see all of them.

<Note>
  `--limit` is capped lower for the table than for JSON because a table is read by a person and JSON is parsed by a program. Use `--format csv` for everything, rather than paging a table.
</Note>

## Paging

Each page prints where it sits in the result set:

```
ℹ Showing 1-20 of 548. Page with --offset 20, or use --format csv to export every row.
```

Pass that offset to get the next page. Page with `next_offset` from the JSON envelope rather than adding `offset + returned_count`: the server counts source rows and drops some while serializing, so the two differ.

## For scripts and agents

`--format json` is a stable contract:

```json theme={null}
{
  "dataset": "terminal-runs",
  "columns": ["Timestamp", "User", "..."],
  "rows": [["2026-08-05T09:55:44Z", "..."]],
  "total_count": 1431,
  "returned_count": 20,
  "offset": 0,
  "next_offset": 20,
  "has_more": true
}
```

Every cell is a string, and `rows` align to `columns`. Page with `--offset next_offset` until `has_more` is `false`.

Diagnostics go to stderr and stdout carries only the payload, so it is safe to pipe. The exit code is `0` on success and `1` on any error.

```bash theme={null}
unbound analytics tool-use terminal --format json --limit 100 \
  | jq -r '.rows[] | @tsv'
unbound analytics tool-use terminal --format json \
  | jq -r '(.columns, .rows[]) | @csv'
```

## Exporting

`--format csv` exports every matching row rather than one page. The file is prepared in the background and the command waits for it — see [Exports](/cli/exports) for how that works, and for exporting Logs, Tasks and Users the same way.

```bash theme={null}
unbound analytics tool-use terminal --start 2026-07-01 --end 2026-07-31 \
  --format csv -o july-terminal-runs.csv
```

<Note>
  Requires CLI **1.15.0** or later.
</Note>