# 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.

{% tabs %}
{% tab title="cURL" %}

```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"
     }'
```

{% endtab %}
{% endtabs %}

**Response (201):**

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

{% 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`, `metrics_to_evaluate`) 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)

{% tabs %}
{% tab title="cURL" %}

```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'
```

{% endtab %}
{% endtabs %}

{% 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.

{% tabs %}
{% tab title="cURL" %}

```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>'
```

{% endtab %}
{% endtabs %}

{% 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 %}

{% tabs %}
{% tab title="cURL" %}

```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'
```

{% endtab %}
{% endtabs %}

**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/diagram content="%%{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](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations)
* [Simulation Unit Test Sets](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-test-sets)
* [Simulation Unit Tests](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-tests)