> ## Documentation Index > Fetch the complete documentation index at: https://docs.usetuner.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run AI-Generated Scenarios > Start an AI-generated simulation run. Tuner generates new test scenarios for your agent, a mix of functional and adversarial, places a call for each, and grades them with the agent's `PASS_FAIL` evals. Scenarios are generated asynchronously, so poll List Runs for progress. To re-test scenarios you've already saved, use Run Saved Scenarios. ## OpenAPI ````yaml https://api.usetuner.ai/public/openapi.json post /api/v1/workspaces/{workspace_id}/agents/{agent_id}/simulation-runs openapi: 3.1.0 info: title: Tuner API description: >- Send calls to Tuner and manage agents, evaluation settings, simulations and workspace settings. version: 1.0.0 servers: - url: https://api.usetuner.ai security: [] tags: - name: calls description: Send call recordings and transcripts to Tuner and retrieve call details. x-group: Calls - name: workspaces description: >- Manage your workspaces, the API keys used to access them, and their PII redaction and data retention settings. x-group: Workspaces - name: simulation description: >- Run simulated calls against your agents, manage simulation profiles, and look up the caller personas and background-noise environments they can use. x-group: Simulation - name: scenarios description: Manage the test scenarios that simulated calls follow. x-group: Scenarios - name: replay-testing description: >- Replay recorded caller audio against a new version of your agent: upload or extract voice clips from real calls, then run them as replay runs. x-group: Replay Testing - name: agents description: Create, update and list the voice agents connected to your workspace. x-group: Agents - name: agent-settings description: >- Configure how Tuner evaluates an agent's calls, including evaluations, call outcomes, intents, data extraction, rules and alerts, plus the agent's SIP and outbound call configuration. x-group: Agent Settings - name: traces description: Send OpenTelemetry traces from your agent to Tuner. x-group: Traces - name: providers description: List the voice providers Tuner can connect to. x-group: Providers paths: /api/v1/workspaces/{workspace_id}/agents/{agent_id}/simulation-runs: post: tags: - simulation summary: Run AI-Generated Scenarios description: >- Start an AI-generated simulation run. Tuner generates new test scenarios for your agent, a mix of functional and adversarial, places a call for each, and grades them with the agent's `PASS_FAIL` evals. Scenarios are generated asynchronously, so poll List Runs for progress. To re-test scenarios you've already saved, use Run Saved Scenarios. operationId: >- create_simulation_run_api_v1_workspaces__workspace_id__agents__agent_id__simulation_runs_post parameters: - name: agent_id in: path required: true schema: type: integer description: Tuner's internal numeric ID for the agent. title: Agent Id description: Tuner's internal numeric ID for the agent. - name: workspace_id in: path required: true schema: type: integer description: Workspace ID. Find this in Workspace > General Settings. title: Workspace Id description: Workspace ID. Find this in Workspace > General Settings. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSimulationRunRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SimulationRunResponse' '400': description: >- `caller_persona_id`, `simulation_profile_id` or `noise_environment_id` does not exist, or the profile belongs to a different agent. content: application/json: example: detail: >- Invalid simulation_profile_id or profile does not belong to this agent schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key. content: application/json: example: detail: Not authenticated schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- The workspace has no credits remaining, or its plan does not include simulations. content: application/json: example: detail: You have no credits remaining. schema: $ref: '#/components/schemas/ErrorResponse' '403': description: You do not have access to this workspace. content: application/json: example: detail: User does not have access to workspace 42 schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent not found. content: application/json: example: detail: Agent with ID 17 not found schema: $ref: '#/components/schemas/ErrorResponse' '409': description: A simulation run is already in progress for this agent. content: application/json: example: detail: You have a simulation run in progress. Come back later. schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The agent has no settings configured, its provider does not support simulations for its call direction, it has no `PASS_FAIL` eval configured, or `selected_eval_ids` or `selected_intent_ids` contains an unknown id. content: application/json: example: detail: >- Agent has no boolean (PASS_FAIL) evals. Add at least one before running a simulation. schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The run was created but could not be started (for example, its calls could not be queued). The run is marked failed; retry the request. content: application/json: example: detail: Could not start the simulation run. Please try again. schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] components: schemas: CreateSimulationRunRequest: properties: max_call_duration_minutes: type: integer maximum: 12 minimum: 1 title: Max Call Duration Minutes description: >- Maximum length of each simulated call, in minutes (1-12). Defaults to 3. default: 3 examples: - 3 caller_persona_id: type: integer title: Caller Persona Id description: >- ID of the caller persona (language and accent) the simulated caller uses. Get valid IDs from List Caller Personas. examples: - 1 simulation_profile_id: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Simulation Profile Id description: >- ID of a simulation profile belonging to this agent. Its fields are given to the simulated caller as facts about themselves. Optional. examples: - 12 noise_environment_id: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' title: Noise Environment Id description: >- ID of a background-noise environment to mix into the call. Get valid IDs from List Noise Environments. Must be sent together with `noise_intensity`. examples: - 2 noise_intensity: anyOf: - type: number - type: 'null' title: Noise Intensity description: >- Gain applied to the background noise: 0.5, 1.0 or 1.5. Must be sent together with `noise_environment_id`. examples: - 1 functional_count: type: integer minimum: 0 title: Functional Count description: Number of functional (routine) scenarios to generate. examples: - 4 adversarial_count: type: integer minimum: 0 title: Adversarial Count description: >- Number of adversarial (pressure) scenarios to generate. `functional_count + adversarial_count` must be between 5 and 20. examples: - 2 selected_eval_ids: anyOf: - items: type: integer type: array - type: 'null' title: Selected Eval Ids description: >- IDs of `PASS_FAIL` evals to grade the calls with. Omit or send `null` to use all of the agent's evals. If provided, it must contain at least one ID. examples: - - 101 - 102 selected_intent_ids: anyOf: - items: type: integer type: array - type: 'null' title: Selected Intent Ids description: >- IDs of call intents to detect on the calls. Omit or send `null` to use all of the agent's intents. If provided, it must contain at least one ID. examples: - - 7 - 8 type: object required: - caller_persona_id - functional_count - adversarial_count title: CreateSimulationRunRequest description: >- Request to start a generated simulation run. Tuner generates `functional_count + adversarial_count` test scenarios (5 to 20 in total), places one simulated call per scenario against the agent, and grades the calls with the agent's `PASS_FAIL` evals. SimulationRunResponse: properties: simulation_run_id: type: integer title: Simulation Run Id description: ID of the new simulation run. generated_count: type: integer title: Generated Count description: >- Number of test scenarios created so far. 0 for Run AI-Generated Scenarios, because generation is asynchronous; the full count for replay runs and runs from saved scenarios. success: type: boolean title: Success description: Whether the run was accepted. caller_persona_id: anyOf: - type: integer - type: 'null' title: Caller Persona Id description: ID of the caller persona used. Null for replay runs. caller_persona: anyOf: - $ref: '#/components/schemas/CallerPersonaResponse' - type: 'null' description: The caller persona used. Null for replay runs. simulation_profile_id: anyOf: - type: integer - type: 'null' title: Simulation Profile Id description: ID of the simulation profile used, if one was given. simulation_profile_name: anyOf: - type: string - type: 'null' title: Simulation Profile Name description: Name of the simulation profile used, if one was given. simulation_profile_snapshot: anyOf: - additionalProperties: true type: object - type: 'null' title: Simulation Profile Snapshot description: Copy of the profile's fields as they were when the run started. noise_environment_id: anyOf: - type: integer - type: 'null' title: Noise Environment Id description: ID of the background-noise environment used, if one was given. noise_intensity: anyOf: - type: number - type: 'null' title: Noise Intensity description: Gain applied to the background noise, if noise was used. noise_environment: anyOf: - $ref: '#/components/schemas/NoiseEnvironmentResponse' - type: 'null' description: The background-noise environment used, if one was given. type: object required: - simulation_run_id - generated_count - success title: SimulationRunResponse description: The simulation run that was just started. ErrorResponse: properties: detail: type: string title: Detail description: Human-readable description of what went wrong. type: object required: - detail title: ErrorResponse description: Error body returned when a request fails. CallerPersonaResponse: properties: id: type: integer title: Id description: >- Persona ID. Pass as `caller_persona_id` when creating a simulation run. examples: - 1 name: type: string title: Name description: Display name of the persona. examples: - English (British) language: type: string title: Language description: Language name. examples: - English language_code: type: string title: Language Code description: Language code. examples: - en accent: type: string title: Accent description: Accent identifier. examples: - British label: type: string title: Label description: Short accent label for display. examples: - UK country_code: type: string title: Country Code description: ISO 3166-1 alpha-2 country code of the accent. examples: - GB type: object required: - id - name - language - language_code - accent - label - country_code title: CallerPersonaResponse description: >- A caller persona: the language and accent a simulated caller speaks with. NoiseEnvironmentResponse: properties: id: type: integer title: Id description: >- Environment ID. Pass as `noise_environment_id` when creating a simulation run. examples: - 1 name: type: string title: Name description: Display name of the environment. examples: - Café slug: type: string title: Slug description: Stable text identifier of the environment. examples: - cafe type: object required: - id - name - slug title: NoiseEnvironmentResponse description: One selectable background environment. securitySchemes: Bearer: type: http description: >- Use Tuner API key (tr_api_...) or user session token. Find your API key in Workspace Settings > API Keys. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.