> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-test-set-runs.md).

# Unit Test Set Runs

Execute simulation test suites and retrieve results. A run executes all unit tests in a unit test set according to their configured run counts, evaluates success criteria, and produces downloadable artifacts with the full results.

{% hint style="warning" %}
**One Active Run Per Set**

A user can have only one unfinished (in-progress) run per unit test set at a time. Attempting to create a second run for the same set returns HTTP 409.
{% endhint %}

## Create a Run

Start a new run for a simulation unit test set. The platform executes all unit tests in the set, running simulated conversations and evaluating metrics.

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set_run/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "simulation_unit_test_set_id": "6618791275130b73714e8d7f"
     }'
```

**Response (201):**

```json
{
  "simulation_unit_test_set_run_id": "6618791275130b73714e8d9a"
}
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test\_set\_run/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## List Runs

Retrieve simulation unit test set runs that match the given filters. Only runs the authenticated user has `Simulation:GetSimulationUnitTestSetRun` permission for are returned.

{% hint style="info" %}
**Conditional Fields**

The `unit_test_run_specs` and `unit_test_run_results` fields are only populated if the authenticated user also has `Simulation:GetSimulationUnitTestSet` permission. Additional nested fields (`scenario_version_info`, `persona_version_info`, and `metrics_to_evaluate` in `unit_test_run_specs`, and `metric_evaluation_results` in `unit_test_run_results`) require `Simulation:GetSimulationUnitTest` permission.
{% endhint %}

Common filters:

* `id=<id>` (repeatable): filter by specific run IDs
* `simulation_unit_test_set_id=<id>` (repeatable): filter by parent test set
* `is_completed=true|false`: filter by completion status
* `failed_metrics=true|false`: filter by pass/fail status
* `errored=true|false`: filter by error status
* `creator=<org_id,user_id>` (repeatable): filter by creator
* `sort_by=+created_at|-created_at` (repeatable)
* `limit` (0-50, default 50), `continuation_token` (int, default 0)

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set_run/?limit=10&is_completed=true' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test\_set\_run/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Cancel a Run

Cancel an in-progress simulation unit test set run. Cancellation is best-effort and may not take effect immediately. The run must still be in progress; attempting to cancel a completed run returns HTTP 409.

```bash
curl --request DELETE \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set_run/<RUN-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>'
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test\_set\_run/{simulation\_unit\_test\_set\_run\_id}/" method="delete" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Get Run Artifacts

Retrieve the artifacts (detailed results) of a completed simulation unit test set run. The response is a pre-signed URL where the artifacts can be downloaded.

{% hint style="warning" %}
**Availability**

Artifacts are only available after a run has completed and artifact generation has finished. If artifacts are not yet ready, this endpoint returns HTTP 400.
{% endhint %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set_run/<RUN-ID>/artifacts/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

**Response (200):**

```json
{
  "presigned_url": "https://artifacts.amigo.ai/...",
  "url_expires_at": "2025-03-15T12:00:00Z"
}
```

The `presigned_url` gives you temporary access to download the artifact file. The URL expires at the time shown in `url_expires_at` (UTC).

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test\_set\_run/{simulation\_unit\_test\_set\_run\_id}/artifacts/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Run Lifecycle

```mermaid
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F"}}}%%
stateDiagram-v2
  direction LR
  [*] --> InProgress: create run
  InProgress --> Completed: all tests finish
  InProgress --> Cancelled: cancel run
  InProgress --> Errored: system error
  Completed --> ArtifactsReady: artifacts generated

  note right of InProgress
    Tests executing; metrics being evaluated
  end note
  note right of ArtifactsReady
    Downloadable via GET artifacts endpoint
  end note
```

## Related

* [Simulation Overview](/developer-guide/classic-api/core-api/simulations.md)
* [Simulation Unit Test Sets](/developer-guide/classic-api/core-api/simulations/simulation-unit-test-sets.md)
* [Simulation Unit Tests](/developer-guide/classic-api/core-api/simulations/simulation-unit-tests.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-test-set-runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.