Skip to main content
POST
Create a run

Authorizations

Authorization
string
header
required

An Egma API key.

Query Parameters

projectId
string

Project to act in. A project-scoped API key already identifies its project.

Minimum string length: 1

Body

application/json
suiteId
string
required

The active, non-empty test suite to execute in full. It must belong to the selected project.

Minimum string length: 1
Example:

"ste_01M0E4J0BBE1FVDVTZ1BSS5C97"

agentId
string
required

The Egma agent to test, not its Retell provider ID or LiveKit dispatch name.

Minimum string length: 1
Example:

"agt_01M0E4J0BBE1FVDVTZ1BSS5C97"

connectionId
string
required

An active connection on that agent in the same project. Its modality determines whether simulations use voice or chat.

Minimum string length: 1
Example:

"con_01M0E4J0BBE1FVDVTZ1BSS5C97"

name
string

Optional display name for the run.

Example:

"Appointment booking release check"

expectedTestVersions
object[]

Optional exact list of the suite's test IDs and current version IDs. Each test and version must appear once. The request is refused if the suite membership or any version changed. Omit this field to use the current suite.

Response

The run header for a new request or an idempotent replay. The run may still be executing or grading.

id
string
required
Minimum string length: 1
projectId
string
required
Minimum string length: 1
suiteId
string
required
Minimum string length: 1
suiteName
string
required
suiteDeleted
boolean
required
name
string | null
required
status
enum<string>
required

Simulation execution status. A completed run can contain failed simulations, and grading may still be in progress.

Available options:
pending,
running,
completed,
canceled
agentId
string
required
Minimum string length: 1
connectionId
string
required
Minimum string length: 1
connectionName
string | null
required
agentPlatform
string | null
required
connectionType
string
required
accessVariant
string
required
modality
enum<string>
required
Available options:
voice,
chat
productLabel
string
required
environment
string | null
required
agentVersion
integer | null
required
expectedSimulationCount
integer
required

Number of test-and-persona combinations captured when the run started.

completedCount
integer | null
required
failedCount
integer | null
required
canceledCount
integer | null
required
simulationCounts
object
required
finishedCount
integer
required

Simulations whose execution completed, failed, or was canceled.

gradableCount
integer
required

Simulations eligible for grading under the run's frozen grader selection.

gradedCount
integer
required

Gradable simulations whose grading is complete or errored. This is not a count of passed simulations.

resultsUrl
string
required

Open this URL in a browser to follow the run and inspect its results.

createdAt
string<date-time>
required
startedAt
string<date-time> | null
required
finishedAt
string<date-time> | null
required