Agent Analytics export API

The export API returns production agent data as JSON so you can run evaluations in your own tooling. The API covers sessions, the datasets you curate in Amplitude, and the evaluator configurations you define. An offline pipeline can read the same sessions and the same judging criteria the product uses.

This API is read-only. To send data in, refer to Send agent events without the AI SDK.

These endpoints aren't part of the OpenAPI-defined Developer API, so they don't appear in that reference and the amp CLI doesn't support them. Call them directly over HTTP.

Authentication and request requirements

• All endpoints use HTTP Basic authentication. Use your project's API key as the username and the secret key as the password. Refer to Find your API key and secret key.
• The authenticated project determines which data you receive. No project_id parameter exists, and a key can't request another project's data.
• Pagination cursors are opaque strings. Pass next_page_token from the previous response unchanged.
• Keep sort_order and all filters identical across every page of one traversal. Pagination reads live data rather than a snapshot, so data that changes during a traversal can change later pages.

Regions

Send requests to the data center that hosts your project.

Keys aren't interchangeable between regions. A US project's key returns 401 against the EU host.

Lookback and session visibility

Two product rules shape what a response contains, and both apply before pagination:

• Lookback window: Your plan's entitlement limits how far back sessions are available. A request for an explicit time range outside that window returns 400 rather than narrowing the range. An organization with no lookback entitlement can't use the session and dataset endpoints. Assign an entitlement before you start.
• Session cap: An organization that reached its session cap can't export newer sessions. Sessions already enriched stay available.

Amplitude reports excluded sessions rather than dropping them silently. Collection responses carry an omissions array that counts what the filters removed and why.

The two collection endpoints exclude a withheld session and count it in omissions. The single-session endpoint returns 403 instead, because there's nothing to omit from.

Omission counts describe the whole matching collection, not the current page. The counts repeat on every page, so don't add them across pages.

List sessions

Returns a paginated list of sessions for the authenticated project, with metadata and human review. Traces, spans, and turns come from the single-session endpoint.

GET /v1/agent-analytics/export/sessions

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions' \
-u '{api_key}:{secret_key}'

Filter by agent and time range:

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions?agent_name=support-bot&start_time=2026-01-01T00%3A00%3A00Z&end_time=2026-01-31T23%3A59%3A59Z&page_size=100' \
-u '{api_key}:{secret_key}'

Fetch the next page:

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions?page_size=100&page_token={next_page_token}' \
-u '{api_key}:{secret_key}'

Query parameters

Response

{
  "sessions": [
    {
      "session": {
        "object": "agent_session",
        "id": "string",
        "project_id": "string",
        "user_id": "string",
        "agent_name": "string",
        "start_time": "2026-01-15T10:00:00.000Z",
        "end_time": "2026-01-15T10:04:12.000Z",
        "duration_ms": 252000,
        "num_traces": 3,
        "num_errors": 0,
        "models_used": ["string"],
        "total_input_tokens": 2406,
        "total_output_tokens": 225,
        "total_cost_usd": 0.001285,
        "status": "enriched",
        "enrichment_status": "completed",
        "last_message": "string",
        "metadata": {}
      },
      "human_review": { "comments": [], "tags": [] }
    }
  ],
  "next_page_token": "string",
  "omissions": [{ "reason": "session_cap", "count": 12 }]
}

Get one session

Returns one session with its full traces, spans, sanitized turns, enrichments, and dataset memberships.

GET /v1/agent-analytics/export/sessions/{session_id}

Use the id from the session list. Session IDs are the identifiers your instrumentation sends, not the numeric row IDs shown elsewhere in Amplitude.

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions/{session_id}' \
-u '{api_key}:{secret_key}'

Response

{
  "session": { "object": "agent_session" },
  "traces": [
    {
      "object": "agent_trace",
      "id": "string",
      "spans": [
        {
          "object": "agent_span",
          "id": "string",
          "name": "llm_completion",
          "attributes": {},
          "raw_input": "string",
          "raw_output": "string"
        }
      ]
    }
  ],
  "turns": [
    {
      "object": "agent_turn",
      "id": "string",
      "trace_id": "string",
      "turn_index": 1,
      "role": "user",
      "latency_ms": 0,
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ],
  "enrichments": [{ "object": "agent_session_enrichment" }],
  "datasets": [],
  "human_review": { "comments": [], "tags": [] },
  "conversation_turn_count": 4,
  "shared_attributes": {}
}

Shared attributes

A span attribute that repeats across spans, such as a system prompt or a tool definition, is stored once in the session-level shared_attributes map. Each occurrence carries a reference in place of the value:

{ "$shared_attribute": "a1b2c3d4" }

Resolve a reference by looking up its value in shared_attributes. Deduplication is lossless, and it can reduce a response from several megabytes to a few hundred kilobytes. A session with nothing repeated returns shared_attributes as an empty object.

A session too large to return in one response fails with 400 rather than returning partial data. An export never silently truncates traces or turns.

Get a dataset

Returns a dataset with a paginated list of its member sessions, including ground-truth labels and human review.

GET /v1/agent-analytics/export/datasets/{dataset_id}

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/datasets/{dataset_id}?page_size=50' \
-u '{api_key}:{secret_key}'

Query parameters

Session filters such as user_id and agent_name aren't valid on this endpoint and return 400.

Response

{
  "dataset": {
    "object": "agent_dataset",
    "id": "string",
    "project_id": "string",
    "name": "string",
    "description": "string",
    "agent_name": "string",
    "source_type": "manual",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z"
  },
  "members": [
    {
      "object": "agent_dataset_member",
      "session_id": "string",
      "added_at": "2026-01-15T10:00:00.000Z",
      "selection_reason": "string",
      "ground_truth_labels": {
        "evaluator_results": {},
        "overridden_evaluators": [],
        "review_status": "partial",
        "reviewed_by": "string",
        "reviewed_at": "2026-01-15T10:00:00.000Z"
      },
      "session": { "object": "agent_session" },
      "human_review": { "comments": [], "tags": [] }
    }
  ],
  "next_page_token": "string",
  "omissions": []
}

Each member carries session metadata only. Request the session individually for its traces and turns.

Get an evaluator configuration

Returns one evaluator configuration, including its prompt, model, and labels, so you can reproduce the same judgment in your own tooling.

GET /v1/agent-analytics/export/evaluators/{evaluator_id}

This endpoint doesn't read session data, so the lookback window and session cap don't apply.

curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/evaluators/{evaluator_id}' \
-u '{api_key}:{secret_key}'

Response

{
  "config": {
    "object": "agent_evaluator",
    "id": "string",
    "project_id": "string",
    "topic": "string",
    "status": "draft",
    "output_type": "binary",
    "run_on": "all",
    "description": "string",
    "tags": [{ "id": "yes", "label": "True", "description": "string", "examples": [] }],
    "prompt": "string",
    "model": "string",
    "evaluation_method": "llm",
    "granularity": "session",
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z"
  }
}

Status and error codes

Errors use application/problem+json with an error_code field and a retryable flag.