---
title: "Create a new prompt-based simulation run."
method: POST
path: "/simulate/prompt-templates/{prompt_template_id}/simulations/"
tags: ["simulate"]
---

# Create a new prompt-based simulation run.

`POST /simulate/prompt-templates/{prompt_template_id}/simulations/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/simulate/prompt-templates/{prompt_template_id}/simulations/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

Request Body:
- name: Name of the simulation run
- description: Optional description
- prompt_version_id: The prompt version to use
- scenario_ids: List of scenario IDs to run
- dataset_row_ids: Optional list of specific row IDs
- evaluations_config: Optional evaluation configurations
- enable_tool_evaluation: Optional boolean to enable tool evaluation

## Request body

- CreatePromptSimulationRequest
  - `name` string, required
  - `description` string
  - `prompt_version_id` string, required: Prompt version ID (UUID) or template_version string
  - `scenario_ids` string[], required
  - `dataset_row_ids` string[]
  - `evaluations_config` EvalConfigDefinition[]: Evaluation configurations to create
    - `template_id` string, uuid, required: UUID of the evaluation template to use.
    - `name` string: Name for this evaluation configuration. Defaults to 'Eval-<template_id>' if omitted.
    - `config` object: Template-specific configuration parameters.
    - `mapping` object: Maps test execution data fields to the evaluation template's expected inputs.
    - `filters` object[]: Canonical filter list to restrict which test results are evaluated.
      - `column_id` string, required: Column or attribute id to filter on.
      - `property_id` string: Optional stable namespaced Property Registry identity.
      - `display_name` string: Optional UI label for chips and saved views.
      - `source` string: Optional source surface for mixed-source filters, for example traces, datasets, or simulation.
      - `output_type` string: Optional metric output type metadata used by eval and annotation filters.
      - `filter_config` object, required
        - `filter_type` string, required: Canonical field type, for example text, number, boolean, datetime, categorical, thumbs, annotator, array, or map. Legacy json is value-sensitive for SPAN_ATTRIBUTE filters: list values become array and object values become map.
        - `filter_op` string, required: Canonical operator from api_contracts/filter_contract.json, for example equals, not_equals, in, not_in, between, not_between, is_null, or is_not_null.
        - `filter_value` unknown
        - `col_type` string: Column family such as SYSTEM_METRIC, SPAN_ATTRIBUTE, EVAL_METRIC, ANNOTATION, or NORMAL.
        - `attribute_value_types` string[]: Optional storage-family provenance aligned one-for-one with filter_value for mixed SPAN_ATTRIBUTE in/not_in filters. Null entries retain filter_type semantics for manually entered values.
    - `error_localizer` boolean: Enables granular error localization on evaluation failures.
    - `model` string, nullable: Model to use for running this evaluation.
    - `kb_id` string, uuid, nullable: Knowledge base file to use for this evaluation.
    - `eval_group` string, uuid, nullable: Eval group that created this evaluation config.
  - `enable_tool_evaluation` boolean: Enable automatic tool evaluation for this simulation run

## Response `201`

Created

- PromptSimulationRunResponse
  - `status` boolean
  - `result` RunTestResponse, required
    - `id` string, uuid
    - `name` string: Name of the test run
    - `description` string, nullable
    - `agent_definition` string, uuid, nullable: Agent definition for this test run
    - `agent_version` object, nullable
    - `agent_definition_detail` object, nullable
    - `source_type` 'agent_definition' | 'prompt': Source type for the test run: agent_definition or prompt
    - `source_type_display` string, nullable
    - `prompt_template` string, uuid, nullable: Prompt template for this test run (only for prompt source type)
    - `prompt_template_detail` object, nullable
    - `prompt_version` string, uuid, nullable: Prompt version for this test run (only for prompt source type)
    - `prompt_version_detail` object, nullable
    - `scenarios` string[]: Scenarios to run in this test
    - `scenarios_detail` object[]
    - `dataset_row_ids` string[]: IDs of dataset rows to run evaluations on
    - `simulator_agent` string, uuid, nullable: Simulator agent for this test run (derived from scenarios)
    - `simulator_agent_detail` object, nullable
    - `simulate_eval_configs` string[]
    - `simulate_eval_configs_detail` SimulateEvalConfigResponse[]
      - `id` string, uuid
      - `name` string, nullable
      - `config` object, nullable
      - `mapping` object, nullable
      - `filters` object[]
        - `column_id` string, required: Column or attribute id to filter on.
        - `property_id` string: Optional stable namespaced Property Registry identity.
        - `display_name` string: Optional UI label for chips and saved views.
        - `source` string: Optional source surface for mixed-source filters, for example traces, datasets, or simulation.
        - `output_type` string: Optional metric output type metadata used by eval and annotation filters.
        - `filter_config` object, required
          - `filter_type` string, required: Canonical field type, for example text, number, boolean, datetime, categorical, thumbs, annotator, array, or map. Legacy json is value-sensitive for SPAN_ATTRIBUTE filters: list values become array and object values become map.
          - `filter_op` string, required: Canonical operator from api_contracts/filter_contract.json, for example equals, not_equals, in, not_in, between, not_between, is_null, or is_not_null.
          - `filter_value` unknown
          - `col_type` string: Column family such as SYSTEM_METRIC, SPAN_ATTRIBUTE, EVAL_METRIC, ANNOTATION, or NORMAL.
          - `attribute_value_types` string[]: Optional storage-family provenance aligned one-for-one with filter_value for mixed SPAN_ATTRIBUTE in/not_in filters. Null entries retain filter_type semantics for manually entered values.
      - `error_localizer` boolean
      - `model` string, nullable
      - `status` string, nullable
      - `eval_group` string, nullable
      - `template_id` string, uuid, nullable
      - `eval_type` string
      - `regradable` boolean
      - `editable` boolean
    - `evals_detail` SimulateEvalConfigResponse[]
      - `id` string, uuid
      - `name` string, nullable
      - `config` object, nullable
      - `mapping` object, nullable
      - `filters` object[]
        - `column_id` string, required: Column or attribute id to filter on.
        - `property_id` string: Optional stable namespaced Property Registry identity.
        - `display_name` string: Optional UI label for chips and saved views.
        - `source` string: Optional source surface for mixed-source filters, for example traces, datasets, or simulation.
        - `output_type` string: Optional metric output type metadata used by eval and annotation filters.
        - `filter_config` object, required
          - `filter_type` string, required: Canonical field type, for example text, number, boolean, datetime, categorical, thumbs, annotator, array, or map. Legacy json is value-sensitive for SPAN_ATTRIBUTE filters: list values become array and object values become map.
          - `filter_op` string, required: Canonical operator from api_contracts/filter_contract.json, for example equals, not_equals, in, not_in, between, not_between, is_null, or is_not_null.
          - `filter_value` unknown
          - `col_type` string: Column family such as SYSTEM_METRIC, SPAN_ATTRIBUTE, EVAL_METRIC, ANNOTATION, or NORMAL.
          - `attribute_value_types` string[]: Optional storage-family provenance aligned one-for-one with filter_value for mixed SPAN_ATTRIBUTE in/not_in filters. Null entries retain filter_type semantics for manually entered values.
      - `error_localizer` boolean
      - `model` string, nullable
      - `status` string, nullable
      - `eval_group` string, nullable
      - `template_id` string, uuid, nullable
      - `eval_type` string
      - `regradable` boolean
      - `editable` boolean
    - `organization` string, uuid: Organization this test run belongs to
    - `enable_tool_evaluation` boolean: Enable automatic tool evaluation for this test run
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `last_run_at` string, date-time, nullable
    - `deleted` boolean
    - `deleted_at` string, date-time, nullable

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `500`: Internal Server Error
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)