Run a simulation

Starts a simulation and returns the run.

Send template to run one of the built-in templates: it supplies the metrics and checks, and for some templates the flows too, so the request only names the agent and the direction. Send plan to describe a simulation yourself and run it once. Send planId to run a plan you already have.

template and plan both resolve to a run plan, returned as simulationRunPlanId. Add saveAsPlan to keep it, or read it back to see exactly what ran. A plan built from a template is a snapshot: retuning the template later never changes what that plan runs, which is what makes a saved one safe to pin in CI.

POST /v1/simulation/run

JavaScript

JavaScript

import Roark from '@roarkanalytics/sdk';

const client = new Roark({
  bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted
});

const response = await client.simulation.run({
  plan: {
    agentEndpoints: [{ id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],
    direction: 'INBOUND',
    maxSimulationDurationSeconds: 300,
    metrics: [{}],
  },
});

console.log(response.data);

200

{
  "data": {
    "simulationRunPlanJobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "PENDING",
    "createdAt": "<string>",
    "simulationRunPlanId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "savedAsPlan": true,
    "simulationJobCount": 123
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

New simulation

Existing plan

From template

A built-in template to run, a simulation to configure and run, or the id of a plan to run.

plan · object · required

The simulation to run: what to call, who calls it, and what to measure.

Show child attributes

saveAsPlan · boolean

Keeps this configuration as a run plan, listed by GET /v1/simulation/plan and re-runnable with planId. Requires plan.name, since a plan you meant to keep should not be filed under a generated one.

Omitted or false gives a one-off. The run still needs a plan to execute, so one is created either way, but it is hidden: it carries this run and nothing else.

variables · object

Values for the {{variables}} the run resolves, overriding whatever the plan has pinned.

An object applies them to the whole run:

{ "orderNumber": "12345", "tier": "gold" }

An array applies them per flow, or to just its happy path or one of its edge cases, when a single set will not do. Each entry carries what it applies to:

[ { "flowId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "flowId": "550e8400-...", "happyPath": true, "variables": { "orderNumber": "55555" } }, { "flowId": "550e8400-...", "edgeCaseId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ]

An entry that narrows to neither covers everything that flow resolves. A flow this plan does not attach, or an edge case that does not belong to the flow, is rejected rather than ignored.

A plan built on scenarios rather than customer flows targets them the same way, with scenarioId in place of flowId. That form is deprecated alongside scenarios themselves, and still accepted so runs against those plans keep working.

Option 1 · object

Option 2 · object[]

Option 3 · object[]

Show child attributes

Example:

{
  "orderNumber": "12345",
  "environment": "staging"
}

Response

200

application/json

The run that was started

data · object · required

A started simulation run.

Show child attributes