Create Replay Run

curl --request POST \
  --url https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voice_clip_set_ids": [
    123
  ],
  "repeat_count": 1,
  "max_call_duration_minutes": 3,
  "selected_eval_ids": [
    123
  ],
  "selected_intent_ids": [
    123
  ],
  "replay_settings": {
    "silence_ms": 1600,
    "min_speech_ms": 1025,
    "inter_turn_delay_ms": 2500,
    "max_wait_ms": 30500,
    "initial_agent_wait_ms": 30500
  }
}
'

import requests

url = "https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs"

payload = {
    "voice_clip_set_ids": [123],
    "repeat_count": 1,
    "max_call_duration_minutes": 3,
    "selected_eval_ids": [123],
    "selected_intent_ids": [123],
    "replay_settings": {
        "silence_ms": 1600,
        "min_speech_ms": 1025,
        "inter_turn_delay_ms": 2500,
        "max_wait_ms": 30500,
        "initial_agent_wait_ms": 30500
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voice_clip_set_ids: [123],
    repeat_count: 1,
    max_call_duration_minutes: 3,
    selected_eval_ids: [123],
    selected_intent_ids: [123],
    replay_settings: {
      silence_ms: 1600,
      min_speech_ms: 1025,
      inter_turn_delay_ms: 2500,
      max_wait_ms: 30500,
      initial_agent_wait_ms: 30500
    }
  })
};

fetch('https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs",
  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([
    'voice_clip_set_ids' => [
        123
    ],
    'repeat_count' => 1,
    'max_call_duration_minutes' => 3,
    'selected_eval_ids' => [
        123
    ],
    'selected_intent_ids' => [
        123
    ],
    'replay_settings' => [
        'silence_ms' => 1600,
        'min_speech_ms' => 1025,
        'inter_turn_delay_ms' => 2500,
        'max_wait_ms' => 30500,
        'initial_agent_wait_ms' => 30500
    ]
  ]),
  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.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs"

	payload := strings.NewReader("{\n  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\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.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs")

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  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\n  }\n}"

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

{
  "simulation_run_id": 123,
  "generated_count": 123,
  "success": true,
  "caller_persona_id": 123,
  "caller_persona": {
    "id": 123,
    "name": "<string>",
    "language": "<string>",
    "language_code": "<string>",
    "accent": "<string>",
    "label": "<string>",
    "country_code": "<string>"
  },
  "simulation_profile_id": 123,
  "simulation_profile_name": "<string>",
  "simulation_profile_snapshot": {},
  "noise_environment_id": 123,
  "noise_intensity": 123,
  "noise_environment": {
    "id": 123,
    "name": "<string>",
    "slug": "<string>"
  }
}

{
  "detail": "Voice clip set(s) [12, 13] are not ready, or do not belong to this agent."
}

{
  "detail": "Not authenticated"
}

{
  "detail": "You have no credits remaining."
}

{
  "detail": "User does not have access to workspace 42"
}

{
  "detail": "Agent with ID 17 not found"
}

{
  "detail": "You have a simulation run in progress. Come back later."
}

{
  "detail": "Voice clip set 'Angry refund caller' (id=12) has a worst-case call duration of 185000ms, which exceeds the 3-minute cap. Increase max_call_duration_minutes."
}

Simulation

Create Replay Run

Start a deterministic replay run against one or more voice clip sets.

A replay plays each selected clip set’s recorded caller turns at the agent, turn by turn, so the caller side is byte-identical between runs — a metric delta is attributable to a pipeline change rather than conversational variance. It places one call per (clip set, repetition), for len(voice_clip_set_ids) * repeat_count calls total, and is inbound-only.

selected_eval_ids of null or [] means no evals — a latency-only run. This deliberately differs from Create Run, where null means “all evals”: a benchmark run’s headline metric is latency, and silently scoring every eval would misrepresent what was measured. Pass explicit eval IDs to grade the replayed calls.

Unlike Create Run, scenarios are written synchronously (no LLM involved — each scenario is a snapshot of one clip set’s clips) and test calls are queued immediately, so generated_count reflects the true total on the 202 response, not zero. Poll List Runs for progress.

POST

api

workspaces

{workspace_id}

agents

{agent_id}

replay-runs

Create Replay Run

curl --request POST \
  --url https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voice_clip_set_ids": [
    123
  ],
  "repeat_count": 1,
  "max_call_duration_minutes": 3,
  "selected_eval_ids": [
    123
  ],
  "selected_intent_ids": [
    123
  ],
  "replay_settings": {
    "silence_ms": 1600,
    "min_speech_ms": 1025,
    "inter_turn_delay_ms": 2500,
    "max_wait_ms": 30500,
    "initial_agent_wait_ms": 30500
  }
}
'

import requests

url = "https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs"

payload = {
    "voice_clip_set_ids": [123],
    "repeat_count": 1,
    "max_call_duration_minutes": 3,
    "selected_eval_ids": [123],
    "selected_intent_ids": [123],
    "replay_settings": {
        "silence_ms": 1600,
        "min_speech_ms": 1025,
        "inter_turn_delay_ms": 2500,
        "max_wait_ms": 30500,
        "initial_agent_wait_ms": 30500
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    voice_clip_set_ids: [123],
    repeat_count: 1,
    max_call_duration_minutes: 3,
    selected_eval_ids: [123],
    selected_intent_ids: [123],
    replay_settings: {
      silence_ms: 1600,
      min_speech_ms: 1025,
      inter_turn_delay_ms: 2500,
      max_wait_ms: 30500,
      initial_agent_wait_ms: 30500
    }
  })
};

fetch('https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs",
  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([
    'voice_clip_set_ids' => [
        123
    ],
    'repeat_count' => 1,
    'max_call_duration_minutes' => 3,
    'selected_eval_ids' => [
        123
    ],
    'selected_intent_ids' => [
        123
    ],
    'replay_settings' => [
        'silence_ms' => 1600,
        'min_speech_ms' => 1025,
        'inter_turn_delay_ms' => 2500,
        'max_wait_ms' => 30500,
        'initial_agent_wait_ms' => 30500
    ]
  ]),
  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.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs"

	payload := strings.NewReader("{\n  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\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.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usetuner.ai/api/v1/workspaces/{workspace_id}/agents/{agent_id}/replay-runs")

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  \"voice_clip_set_ids\": [\n    123\n  ],\n  \"repeat_count\": 1,\n  \"max_call_duration_minutes\": 3,\n  \"selected_eval_ids\": [\n    123\n  ],\n  \"selected_intent_ids\": [\n    123\n  ],\n  \"replay_settings\": {\n    \"silence_ms\": 1600,\n    \"min_speech_ms\": 1025,\n    \"inter_turn_delay_ms\": 2500,\n    \"max_wait_ms\": 30500,\n    \"initial_agent_wait_ms\": 30500\n  }\n}"

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

{
  "simulation_run_id": 123,
  "generated_count": 123,
  "success": true,
  "caller_persona_id": 123,
  "caller_persona": {
    "id": 123,
    "name": "<string>",
    "language": "<string>",
    "language_code": "<string>",
    "accent": "<string>",
    "label": "<string>",
    "country_code": "<string>"
  },
  "simulation_profile_id": 123,
  "simulation_profile_name": "<string>",
  "simulation_profile_snapshot": {},
  "noise_environment_id": 123,
  "noise_intensity": 123,
  "noise_environment": {
    "id": 123,
    "name": "<string>",
    "slug": "<string>"
  }
}

{
  "detail": "Voice clip set(s) [12, 13] are not ready, or do not belong to this agent."
}

{
  "detail": "Not authenticated"
}

{
  "detail": "You have no credits remaining."
}

{
  "detail": "User does not have access to workspace 42"
}

{
  "detail": "Agent with ID 17 not found"
}

{
  "detail": "You have a simulation run in progress. Come back later."
}

{
  "detail": "Voice clip set 'Angry refund caller' (id=12) has a worst-case call duration of 185000ms, which exceeds the 3-minute cap. Increase max_call_duration_minutes."
}

Authorizations

Authorization

string

header

required

Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys.

Path Parameters

agent_id

integer

required

Tuner's internal numeric ID for the agent.

workspace_id

integer

required

Workspace ID. Find this in Workspace > General Settings.

Body

application/json

Request to launch a deterministic replay run against one or more voice clip sets.

voice_clip_set_ids

integer[]

required

Required array length: 1 - 10 elements

repeat_count

integer

default:1

Required range: 1 <= x <= 20

max_call_duration_minutes

integer

default:3

Required range: 1 <= x <= 12

selected_eval_ids

integer[] | null

selected_intent_ids

integer[] | null

replay_settings

ReplaySettingsInput · object | null

User-supplied overrides for a replay's timing policy.

Every field is optional; an unset field falls back to the corresponding default on app.services.simulation_clip_replay.ReplaySettings -- the single source of truth for these defaults, deliberately not duplicated here.

Show child attributes

Response

Successful Response

simulation_run_id

integer

required

generated_count

integer

required

success

boolean

required

caller_persona_id

integer | null

caller_persona

CallerPersonaResponse · object | null

Show child attributes

simulation_profile_id

integer | null

simulation_profile_name

string | null

simulation_profile_snapshot

Simulation Profile Snapshot · object | null

noise_environment_id

integer | null

noise_intensity

number | null

noise_environment

NoiseEnvironmentResponse · object | null

One selectable background environment.

Show child attributes