---
title: "amp agent-analytics"
description: "Reference for amp agent-analytics, which reads saved insights and manages datasets, evaluators, and eval runs."
product: general
lang: en
last_updated: 2026-11-18
token_estimate: 2891
---
# amp agent-analytics

`amp agent-analytics` reads saved Agent Analytics insights and manages datasets, evaluators, and eval runs. Read commands require `analytics:read`; commands that change data require `analytics:write`.

## `amp agent-analytics insights list`

Returns saved cost, efficiency, and quality findings, ranked by magnitude times confidence. These are periodically evaluated findings, not live queries. Healthy and closed findings can remain visible. Thumbs-downed findings are excluded. Use each finding's project\_id for individual reads.

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--limit` | integer | No | Number of items to return. Defaults to 50, max 200. |
| `--cursor` | string | No | Opaque cursor from `pagination.next_cursor` on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 `pagination_not_supported`. Alias: `--next-cursor`. |
| `--agent-name` | string | No | Exact agent name. Omit for all scopes; an empty string selects project-level findings only. |

Requires the `analytics:read` scope.

## `amp agent-analytics insights get`

Returns one finding by its stable UUID and own project\_id. Missing, cross-project, and thumbs-downed findings return 404.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--insight-id` | string | Yes | Stable insight UUID returned by the list operation, not a finding key such as tool-failures. |

Requires the `analytics:read` scope.

## `amp agent-analytics datasets create`

Creates an empty dataset. Add sessions with the dataset sessions endpoint. `name` is not an identity key, so repeating a create makes another dataset, even with the same `Idempotency-Key`.

Listing and reading datasets is served by the Agent Analytics MCP read surface, not by this API.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--name` | string | Yes |  |
| `--description` | string | No |  |
| `--agent-name` | string | No | Scope the dataset to one agent. Omit for a project-level dataset. |

Requires the `analytics:write` scope.

## `amp agent-analytics datasets update`

Updates dataset metadata. Absent fields are unchanged; an explicit `null` clears `description`. `id`, `agent_name`, and `source_type` are immutable — create a new dataset to change the agent scope.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--dataset-id` | string | Yes | Stable dataset identifier, returned by create or by the Agent Analytics read surface. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--name` | string | No |  |
| `--description` | string | No |  |

Requires the `analytics:write` scope.

## `amp agent-analytics datasets remove-sessions`

Removes sessions from a dataset. The sessions themselves are untouched; only their dataset membership is removed. Sessions that are not in the dataset are ignored, so the call is safe to repeat.

Takes the same body as the add operation, so an add is undone in one call rather than one call per session. `dry_run=true` validates the dataset and the session ids without mutating, returning `204` on a hit and `404` if the dataset does not exist.

Requires --yes to apply changes, or --dry-run when supported to validate without applying changes.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--dataset-id` | string | Yes | Stable dataset identifier, returned by create or by the Agent Analytics read surface. |
| `--dry-run` | boolean | No | Validate request without performing mutation. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--session-ids` | array | Yes | Session identifiers. All must belong to the path project. JSON array, or a comma-separated list for strings. |

Requires the `analytics:write` scope.

## `amp agent-analytics datasets add-sessions`

Adds sessions to a dataset. Sessions already in the dataset are ignored, so the call is safe to repeat. Every session must belong to the path project; a session from another project fails the whole request with `422`.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--dataset-id` | string | Yes | Stable dataset identifier, returned by create or by the Agent Analytics read surface. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--session-ids` | array | Yes | Session identifiers. All must belong to the path project. JSON array, or a comma-separated list for strings. |

Requires the `analytics:write` scope.

## `amp agent-analytics evaluators create`

Creates an evaluator in the inactive state. Activation is a separate permission and is not exposed by this API — activate in the Agent Analytics UI once the evaluator has been reviewed.

`tags` constrains what a result may record. Supplying them for a `binary` or `categorical` evaluator is what keeps results to a known set of values rather than free-form model output.

Listing and reading evaluators is served by the Agent Analytics MCP read surface, not by this API.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--topic` | string | Yes | Human-readable evaluator name. |
| `--output-type` | string: `binary`, `categorical`, `score` | Yes |  |
| `--description` | string | Yes | Evaluator prompt or rubric. |
| `--tags` | array | No | Required for `binary` and `categorical` evaluators. JSON array, or a comma-separated list for strings. |
| `--suite-id` | string | No |  |

Requires the `analytics:write` scope.

## `amp agent-analytics evaluators update`

Updates an evaluator addressed by its stable identifier. Absent fields are unchanged. Each update creates a new inactive version; the response `id` is that new version, and `stable_id` is unchanged.

Updating does not activate. An evaluator already active in the UI keeps serving its current active version until the new one is promoted there.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--evaluator-stable-id` | string | Yes | Evaluator identifier that survives updates. Prefer this over a version identifier, which changes each time the evaluator is updated. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--topic` | string | No |  |
| `--description` | string | No |  |
| `--tags` | array | No | Replaces the full tag set when present. JSON array, or a comma-separated list for strings. |
| `--suite-id` | string | No |  |

Requires the `analytics:write` scope.

## `amp agent-analytics eval-runs list`

Returns eval runs for the project, most recent first. A run is a batch evaluation of sessions by one or more evaluators; it is asynchronous, so a freshly triggered run is returned with a pending status and no results.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--limit` | integer | No | Number of items to return. Defaults to 50, max 200. |
| `--cursor` | string | No | Opaque cursor from `pagination.next_cursor` on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 `pagination_not_supported`. Alias: `--next-cursor`. |
| `--status` | string | No | Filter to runs in one lifecycle state. |

Requires the `analytics:read` scope.

## `amp agent-analytics eval-runs get`

Returns one eval run by id, including progress counters and, once the run finishes, cost and latency. Per-session results are read through the Agent Analytics read surface, not here.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--eval-run-id` | string | Yes | Stable eval run identifier returned by trigger or list. |

Requires the `analytics:read` scope.

## `amp agent-analytics eval-runs trigger`

Starts an asynchronous eval run and returns it immediately with a pending status. Poll the run by id, or read results through the Agent Analytics read surface once it completes.

Target the run either at a dataset or at a session list, not both. Caps are enforced server-side: 10 evaluators and 100 targeted sessions per run. For larger datasets, only the first 100 members are targeted and the acceptance response includes a truncation warning. This selection warning is not persisted on the run returned by later get/list calls.

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--evaluator-ids` | array | Yes | Evaluator version identifiers returned by create or update. Evaluator updates use stable identifiers instead. JSON array, or a comma-separated list for strings. |
| `--dataset-id` | string | No | Evaluate the sessions in this dataset. Mutually exclusive with `session_ids`; exactly one of the two is required. |
| `--session-ids` | array | No | Evaluate these sessions. Mutually exclusive with `dataset_id`; exactly one of the two is required. JSON array, or a comma-separated list for strings. |
| `--sample-size` | integer | No | Retained for compatibility. This endpoint targets explicit session IDs, including when expanding a dataset, so sample\_size does not reduce the selected sessions. All supplied IDs are targeted, with dataset expansion capped at the first 100 members. |

Requires the `analytics:write` scope.

