Start, Follow, and Cancel Agent Simulation Runs via API

A run is an execution of one or more test versions against a specific agent connection. When you start a run, Egma pins the exact test versions you named, freezes the project’s mock-tool world as it stands at that moment, and dispatches one simulation per test-version-and-persona combination. Each simulation proceeds through a defined lifecycle, and when all simulations finish, Egma folds their grader judgments into a single run-level verdict. Runs always execute against pinned test version ids — never “whatever is current”. This means the test you edited after a run started never touches that run’s results. If you name a version id Egma cannot find, or name the same id twice, the entire run creation is refused before a single row is written. You can follow a run in real time using the events feed, which operates as a numbered cursor: if your connection drops, request again from the last sequence number you applied and you will miss nothing.

Start a run

POST /api/runs Start a new run by specifying the test versions to execute and the connection to use. Returns 201 Created with the full run object, including every simulation in queued state. The connection type must have a compatible adapter installed on this deployment. If you attempt a phone run on a deployment without a carrier configured, Egma returns phone_setup_required before writing anything.

Request body

string[]

required

The tstv_… version ids to execute. Each id must be unique in the list and must be a version your credential can read. An empty list starts nothing.

string

required

The connection id to run the simulations against. This determines which agent and provider handle the calls.

string

Optional agent id (agt_…). When supplied, Egma verifies the named connection belongs to this agent and refuses with a clear message if it does not. Useful when a client holds both ids and wants to catch mismatches explicitly.

string

An optional human-readable label for this run, e.g. a branch name, deploy SHA, or release tag.

string

Project context. Defaults to the project your API key belongs to.

Response fields

string

Unique run identifier (run_…).

string

Current run status. Starts as running when simulations are dispatched.

string

The agent the run is executing against.

string

The connection used for this run.

string

Provider type, e.g. retell or livekit.

string

Always voice for current connection types.

string | null

The label supplied at creation, or null.

string[]

The pinned version ids this run executes. These never change after creation.

object

The mock-tool world frozen at the moment this run started.

Show mock_tools fields

object[]

Project-level mock tools frozen for this run. Each entry has tool, answer or error, delay_ms, and mock_tool_id (the source row).

object

Per-test-version overrides, keyed by tstv_… version id. Each value is an array of mock tool entries with the same tool/answer/error/delay_ms shape.

integer

Total number of simulations this run will conduct.

integer | null

Number of simulations that completed successfully. null until the run finishes (all three counts arrive together).

integer | null

Number of simulations that were graded as failed. null until the run finishes.

integer | null

Number of simulations that were canceled. null until the run finishes.

string

A shareable URL to view the results in the Egma web UI. No token or query parameter — open it with any signed-in browser.

string | null

The run-level verdict once grading is complete: passed, failed, skipped, or errored. null while grading is still in progress.

number | null

Aggregate score across all required graders, or null while ungraded.

object | null

Grading counts (passed, failed, skipped, errored) at the run level, or null while ungraded.

object | null

Folded outcome for diagnostic-only (non-required) graders. null if no diagnostic graders are configured. Contains verdict, score, and counts.

object[]

Per-grader verdict breakdown once grading is complete. Each entry includes grader_id, required, verdict, score, and counts.

integer

Number of simulations that have been graded so far. This settles independently of execution — a run can have all simulations completed but still show graded_count less than expected_simulation_count.

object[]

Every simulation in this run.

Show simulation fields

string

Simulation identifier.

integer

Order within the run.

string

The test this simulation is for (go here to edit).

string

The test’s current display name.

string

The exact version that was executed (immutable).

string | null

The persona used for this simulation.

string | null

The persona’s display name.

string

Simulation status: queued, running, completed, failed, errored, or canceled.

string

pending or graded.

string | null

Simulation-level verdict: passed, failed, skipped, or errored. null while ungraded.

number | null

Simulation-level score, or null while ungraded.

object | null

Per-verdict assertion counts at the simulation level, or null while ungraded.

object | null

Folded diagnostic outcome for this simulation, or null if no diagnostic graders are configured.

object[]

Individual assertion judgments. Each entry has grader_id, assertion, assertion_text, required, verdict, score, rationale, cited_turns, and judged_at.

string | null

The reason the conversation ended (e.g. hangup signal or error message).

object | null

Which tools were discovered, covered, and uncovered. null if the agent was never asked about its tools.

string

The modality of this specific conversation.

boolean

true if a recording exists. Use GET /api/simulations/:simulationId/recording to get a playback URL.

string

ISO 8601 timestamp of when the run was started.

string | null

ISO 8601 timestamp of when the run finished, or null while still running.

Example

curl -X POST https://your-egma-host/api/runs \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "test_versions": ["tstv_01abc", "tstv_01def"],
    "connection": "con_01ghi",
    "label": "release/v2.4.0"
  }'

Get a run

GET /api/runs/:runId Retrieve the full run object with all simulations, current statuses, and grading results. Use this to seed a follower that did not start the run, or to get a complete snapshot at any point.

Path parameters

string

required

The run_… identifier of the run.

Response fields

Same shape as the start-run response.

Example

curl "https://your-egma-host/api/runs/run_01abc" \
  -H "Authorization: Bearer <api-key>"

Stream run events

GET /api/runs/:runId/events Poll for changes to a run since a given sequence number. This endpoint is a numbered cursor, not a WebSocket: call it repeatedly, advancing after with the next value each time. If your connection drops, restart from the last next value you applied — you will miss nothing and replay nothing. done: true in the response means the run has finished and no further events will be produced.

Path parameters

string

required

The run_… identifier of the run to follow.

Query parameters

integer

The sequence number to start after. Omit (or use 0) to read from the very first event. Must be a plain non-negative integer — hex, scientific notation, and decimals are rejected.

Response fields

object[]

Events since the requested sequence number, in order.

Show event fields

integer

Sequence number. Use this value as after on the next request.

string

ISO 8601 timestamp.

string

run for run-level changes or simulation for simulation-level changes.

string

New status value.

string

Present on simulation events: the simulation that changed.

string

Present on simulation events: the test being executed.

string

Present on simulation events: the persona conducting the call.

string | null

Present on simulation events: the simulation’s verdict once graded, or null.

string | null

Present on simulation events: the reason the conversation ended, or null.

integer | null

Pass this as ?after on your next request. null means there are no new events yet (poll again) unless done is also true.

boolean

true when the run has finished and no more events will be produced.

Example — initial poll

curl "https://your-egma-host/api/runs/run_01abc/events" \
  -H "Authorization: Bearer <api-key>"

Example — subsequent poll

curl "https://your-egma-host/api/runs/run_01abc/events?after=42" \
  -H "Authorization: Bearer <api-key>"

Cancel a run

POST /api/runs/:runId/cancel Stop a run. Simulations still in queued state are canceled immediately. Simulations already dispatched to a conductor receive a stop signal and land as canceled when they acknowledge it. Canceling a run that is already canceled is a no-op and returns the run as-is. Canceling a run that has already finished is refused with 409 Conflict. The response is the full run object as it stands after the cancel, so you can read the final counts without a second request. The completed_count, failed_count, and canceled_count fields remain null until all three settle together at the finish.

Path parameters

string

required

The run_… identifier of the run to cancel.

Response fields

Same shape as the start-run response: the full run object at its post-cancel state.

Example

curl -X POST "https://your-egma-host/api/runs/run_01abc/cancel" \
  -H "Authorization: Bearer <api-key>"

Get a simulation recording

GET /api/simulations/:simulationId/recording Retrieve a short-lived signed URL to play back the audio recording of a voice simulation. The URL points directly to the object store; Egma only decides whether you may hear it and then signs. Audio bytes are served directly from storage, so seeking is free. This endpoint is only meaningful for voice simulations that completed a call. Chat simulations have no recording. A simulation whose call never connected has no recording either.

Path parameters

string

required

The simulation identifier.

Response fields

string

The simulation this recording belongs to.

string

A short-lived signed URL. Pass directly to an audio player or <audio> element.

string

ISO 8601 timestamp of when the URL expires. If the URL has expired, request this endpoint again for a fresh one.

integer | null

The audio bandwidth the recording was measured at (e.g. 8000 for narrow-band telephone audio, 16000 for wideband). null for recordings written before this measurement was introduced. Two simulations with different bands are different units: a narrow-band recording strips what an audio grader reads.

Example

curl "https://your-egma-host/api/simulations/sim_01abc/recording" \
  -H "Authorization: Bearer <api-key>"

Overview

Agents & Tests

Graders

Telemetry

Account

Start, Follow, and Cancel Agent Simulation Runs via API

Start a run

Request body

Response fields

Example

Get a run

Path parameters

Response fields

Example

Stream run events

Path parameters

Query parameters

Response fields

Example — initial poll

Example — subsequent poll

Cancel a run

Path parameters

Response fields

Example

Get a simulation recording

Path parameters

Response fields

Example

​Start a run

​Request body

​Response fields

​Example

​Get a run

​Path parameters

​Response fields

​Example

​Stream run events

​Path parameters

​Query parameters

​Response fields

​Example — initial poll

​Example — subsequent poll

​Cancel a run

​Path parameters

​Response fields

​Example

​Get a simulation recording

​Path parameters

​Response fields

​Example

Start a run

Request body

Response fields

Example

Get a run

Path parameters

Response fields

Example

Stream run events

Path parameters

Query parameters

Response fields

Example — initial poll

Example — subsequent poll

Cancel a run

Path parameters

Response fields

Example

Get a simulation recording

Path parameters

Response fields

Example