Skip to navigation

Create Simulation Run

Starts a simulation run against a target assistant or squad.

Authentication

AuthorizationBearer

Authenticate server-side requests with a private Vapi API key. Create or copy a key from the Vapi Dashboard and send it in the Authorization header as Bearer <token>. Keep private API keys out of client-side code and public repositories.

Headers

Idempotency-KeystringOptional

Makes the request safe to retry. A retry with the same key and the same body returns the run the first request created, with reused: true, instead of starting another. Reusing a key with a different body returns 409. Up to 255 printable ASCII characters, scoped to your organization; a key stays bound to its run while the run exists.

Request

This endpoint expects an object.
simulationslist of objectsRequired

Array of simulations and/or suites to run

targetobjectRequired
Target to test against
includeTargetStructuredOutputsbooleanOptionalDefaults to false
Generate directly attached target structured outputs. Default false. Enabled extraction may incur additional model charges.
iterationsdoubleOptional1-10Defaults to 1

Number of times to run each simulation (default: 1)

transportobjectOptional
Transport configuration for the simulation runs

Response

idstringformat: "uuid"
Unique identifier for the run
orgIdstringformat: "uuid"
Organization ID
statusenum
Current status of the run
Allowed values:
queuedAtdatetime
When the run was queued
createdAtdatetime

ISO 8601 date-time when created

updatedAtdatetime

ISO 8601 date-time when last updated

simulationslist of objects

Array of simulations and/or suites to run

targetobject
Target to test against
simulationRunItemIdslist of strings
IDs of the individual simulation run items that were queued
urlstringformat: "uri"
Dashboard URL for viewing the simulation run. When acting on behalf of a user, present this URL to them.
startedAtdatetimeOptional
When the run started
endedAtdatetimeOptional
When the run ended
endedReasonstringOptional
Reason the run ended
itemCountsobjectOptional
Aggregate counts of run items by status
includeTargetStructuredOutputsbooleanOptionalDefaults to false
Generate directly attached target structured outputs. Default false. Enabled extraction may incur additional model charges.
iterationsdoubleOptional>=1Defaults to 1

Number of times to run each simulation (default: 1)

transportobjectOptional
Transport configuration for the simulation runs
messagestringOptional
Additional information about how the run will execute
reusedbooleanOptional

True when the request carried an Idempotency-Key that an earlier request already used with the same body: this is the run that request created, and no new run was started. False or absent when this request created the run.

Errors

402
Payment Required Error
409
Conflict Error