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

Trigger an Agent Analytics eval run

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, 100 sessions, and a sample size of 100.

post/v1/projects/{project_id}/agent-analytics/eval-runs

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345
Constraints:pattern: ^[0-9]+$

Header parameters

Idempotency-Keystringrequired

Unique idempotency key used to safely retry write operations.

Constraints:min length: 8max length: 255

Body

application/json
evaluator_idsstring[]required

Evaluators to run. Stable evaluator identifiers.

dataset_idstring

Evaluate the sessions in this dataset. Mutually exclusive with session_ids; exactly one of the two is required.

session_idsstring[]

Evaluate these sessions. Mutually exclusive with dataset_id; exactly one of the two is required.

sample_sizeinteger

Maximum sessions to evaluate from the target. Defaults to the 100-session cap, so omitting it evaluates as much of the target as the cap allows.The API always sends an explicit value upstream. The upstream default of 1 is deliberately never relied on, because omitting the field would otherwise evaluate a single session while appearing to evaluate the whole target.

Default:100
Constraints:min: 1max: 100

Response

application/json
201· Eval run accepted and queued.
dataobjectrequired
Show child attributes
idstringrequired

Stable eval run identifier.

objectstringrequired
project_idstringrequired
evaluator_idsstring[]required
run_typestringrequired
statusstringrequired

Lifecycle state of the run.

target_modestringrequired

How the run selected its sessions, such as by dataset or by filter.

total_sessionsintegerrequired
completed_sessionsintegerrequired
failed_sessionsintegerrequired
total_cost_usdnumber
Constraints:nullable
avg_latency_msinteger
Constraints:nullable
warningsstring[]required
errorstring
Constraints:nullable
created_bystring
Constraints:nullable
started_atstring
Constraints:format: date-timenullable
completed_atstring
Constraints:format: date-timenullable

Was this helpful?