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 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.

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

Required on write operations. Keys aren't stored yet, so retrying a write with the same key performs it again; a retried create makes another resource. Check whether the first attempt succeeded before you retry.

Constraints:min length: 8max length: 255

Body

application/json
One of 2 shapes:
evaluator_idsstring[]required

Evaluator version identifiers returned by create or update. Evaluator updates use stable identifiers instead.

dataset_idstringrequired

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

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.

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?

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.