Simulation

Run a simulation

Runs a simulation and returns the run that was started.

Describe the simulation in plan, or name an existing one with planId. Every run is backed by a run plan, but you only get one you can see and re-use if you ask for it with saveAsPlanName; otherwise the plan is created hidden and simply carries the run.

This replaces creating a plan and then starting a job against it. The response carries simulationJobCount, the number of calls the run places, each of which is billed.

POST

simulation

run

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();

console.log(response.data);

import os
from roark_analytics import Roark

client = Roark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.simulation.run()
print(response.data)

curl --request POST \
  --url https://api.roark.ai/v1/simulation/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "saveAsPlanName": "Billing regression",
  "variables": {
    "orderNumber": "12345",
    "environment": "staging"
  },
  "flowVariables": [
    {
      "flowId": "550e8400-e29b-41d4-a716-446655440000",
      "variables": {
        "orderNumber": "12345"
      }
    },
    {
      "flowId": "550e8400-e29b-41d4-a716-446655440000",
      "variantId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e",
      "variables": {
        "orderNumber": "67890"
      }
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.roark.ai/v1/simulation/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'planId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'saveAsPlanName' => 'Billing regression',
    'variables' => [
        'orderNumber' => '12345',
        'environment' => 'staging'
    ],
    'flowVariables' => [
        [
                'flowId' => '550e8400-e29b-41d4-a716-446655440000',
                'variables' => [
                                'orderNumber' => '12345'
                ]
        ],
        [
                'flowId' => '550e8400-e29b-41d4-a716-446655440000',
                'variantId' => '7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e',
                'variables' => [
                                'orderNumber' => '67890'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.roark.ai/v1/simulation/run"

	payload := strings.NewReader("{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.roark.ai/v1/simulation/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.roark.ai/v1/simulation/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "type": "validation",
  "code": "invalid_parameter",
  "message": "The request was invalid",
  "param": "email"
}

{
  "type": "authentication",
  "code": "unauthorized",
  "message": "Authentication required"
}

{
  "type": "payment_required",
  "code": "insufficient_credits",
  "message": "Not enough credit to start this work. Add credit and try again."
}

{
  "type": "forbidden",
  "code": "permission_denied",
  "message": "You do not have permission to access this resource"
}

{
  "type": "not_found",
  "code": "resource_not_found",
  "message": "The requested resource could not be found"
}

{
  "type": "rate_limit",
  "code": "too_many_requests",
  "message": "Rate limit exceeded"
}

{
  "type": "internal",
  "code": "internal_error",
  "message": "Internal server error"
}

Authorizations

Authorization

string

header

required

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

Body

application/json

Input for running a simulation, either from an inline configuration or an existing plan.

plan

object

The simulation to run. A run plan is created for it behind the scenes.

Show child attributes

planId

string<uuid>

Run a plan that already exists instead of describing one. Mutually exclusive with plan.

saveAsPlanName

string

Keep this run as a reusable plan under this name.

Left unset, the run still needs a plan to execute, but it is created hidden: it does not appear in GET /v1/simulation/plan and exists only to carry the run. Applies only alongside plan, since planId names a plan that already exists.

Minimum string length: 1

Example:

"Billing regression"

variables

object

Runtime variables that override the values defined on the plan. Accepts one of two formats:

Option 1, global (a flat key-value object): { "orderNumber": "12345", "environment": "staging" }

Option 2, per-scenario (an array of objects with scenarioId + variables): [ { "scenarioId": "550e8400-...", "variables": { "orderNumber": "12345" } }, { "scenarioId": "7a3d2e1f-...", "variables": { "orderNumber": "67890" } } ]

On a flow-based plan the global format applies to every variant the run resolves. The per-scenario format targets scenarios, so use flowVariables to override a specific flow or variant instead.

object
object[]

Show child attributes

Example:

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

flowVariables

object[]

Runtime variable overrides targeted at the plan’s customer flows, taking precedence over the values pinned on the flow attachment.

An entry without variantId applies to every variant the attachment resolves. A flow that is not attached to this plan, or a variant that does not belong to the flow, is rejected rather than ignored.

Show child attributes

Example:

[
  {
    "flowId": "550e8400-e29b-41d4-a716-446655440000",
    "variables": { "orderNumber": "12345" }
  },
  {
    "flowId": "550e8400-e29b-41d4-a716-446655440000",
    "variantId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e",
    "variables": { "orderNumber": "67890" }
  }
]

Response

The run that was started

data

object

required

A started simulation run.

Show child attributes

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();

console.log(response.data);

import os
from roark_analytics import Roark

client = Roark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.simulation.run()
print(response.data)

curl --request POST \
  --url https://api.roark.ai/v1/simulation/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "saveAsPlanName": "Billing regression",
  "variables": {
    "orderNumber": "12345",
    "environment": "staging"
  },
  "flowVariables": [
    {
      "flowId": "550e8400-e29b-41d4-a716-446655440000",
      "variables": {
        "orderNumber": "12345"
      }
    },
    {
      "flowId": "550e8400-e29b-41d4-a716-446655440000",
      "variantId": "7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e",
      "variables": {
        "orderNumber": "67890"
      }
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.roark.ai/v1/simulation/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'planId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'saveAsPlanName' => 'Billing regression',
    'variables' => [
        'orderNumber' => '12345',
        'environment' => 'staging'
    ],
    'flowVariables' => [
        [
                'flowId' => '550e8400-e29b-41d4-a716-446655440000',
                'variables' => [
                                'orderNumber' => '12345'
                ]
        ],
        [
                'flowId' => '550e8400-e29b-41d4-a716-446655440000',
                'variantId' => '7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e',
                'variables' => [
                                'orderNumber' => '67890'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.roark.ai/v1/simulation/run"

	payload := strings.NewReader("{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.roark.ai/v1/simulation/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.roark.ai/v1/simulation/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"saveAsPlanName\": \"Billing regression\",\n  \"variables\": {\n    \"orderNumber\": \"12345\",\n    \"environment\": \"staging\"\n  },\n  \"flowVariables\": [\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variables\": {\n        \"orderNumber\": \"12345\"\n      }\n    },\n    {\n      \"flowId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"variantId\": \"7a3d2e1f-c4b5-6a89-0d1e-2f3a4b5c6d7e\",\n      \"variables\": {\n        \"orderNumber\": \"67890\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "type": "validation",
  "code": "invalid_parameter",
  "message": "The request was invalid",
  "param": "email"
}

{
  "type": "authentication",
  "code": "unauthorized",
  "message": "Authentication required"
}

{
  "type": "payment_required",
  "code": "insufficient_credits",
  "message": "Not enough credit to start this work. Add credit and try again."
}

{
  "type": "forbidden",
  "code": "permission_denied",
  "message": "You do not have permission to access this resource"
}

{
  "type": "not_found",
  "code": "resource_not_found",
  "message": "The requested resource could not be found"
}

{
  "type": "rate_limit",
  "code": "too_many_requests",
  "message": "Rate limit exceeded"
}

{
  "type": "internal",
  "code": "internal_error",
  "message": "Internal server error"
}

API Reference

Health

Agent Endpoint

Agent

Call

Chat

Metric

Metric Policy

Metric Collection Job

Simulation Persona

Simulation

Simulation Scenario

Simulation Customer Flow

Simulation Customer Flow Variant

Simulation Environment

Simulation Run Plan

Simulation Run Plan Job

Simulation Job

HTTP Request Definition

Webhook

Issue

Knowledge Base

Run a simulation

Authorizations

Body

Response