Start a run

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a run

> Queue an asynchronous run for one test set.

Queues a run and returns the created run with `status: "running"` and `result: null`. Poll [Get a run](/en/api-reference/get-test-set-run) until `status` becomes `completed` or `failed`.

<Warning>
  Use `simulate` unless live side effects are intentional. `execute` can call your configured external APIs once for every replayed conversation in the set.
</Warning>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `write` scope.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Path parameters

<ParamField path="testSetId" type="string" required>
  Test set ID.
</ParamField>

## Body parameters

<ParamField body="ruleExecutionMode" type="enum">
  How Rulebook logic runs during the replay. Supported values: `reuse`, `simulate`, and `execute`. Defaults to `simulate`.
</ParamField>

<ParamField body="promptVersionId" type="string">
  Optional Behavior version ID to use for the run. Only valid when `ruleExecutionMode` is `simulate` or `execute`.
</ParamField>

## Response

Returns the created [Run object](/en/api-reference/test-sets#run-object).

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request POST \
    --url 'https://api-prod.usefini.com/v2/test-sets/44c1f705-8e1a-4f61-8c4c-d519d37fb6b7/runs/public' \
    --header 'Authorization: Bearer fini_your_api_key' \
    --header 'Content-Type: application/json' \
    --data '{
      "ruleExecutionMode": "simulate",
      "promptVersionId": "9bc3fb9f-85fd-496e-90b3-bcc80ff12d70"
    }'
  ~~~

  ~~~javascript Node.js theme={null}
  const testSetId = '44c1f705-8e1a-4f61-8c4c-d519d37fb6b7';

  const response = await fetch(`https://api-prod.usefini.com/v2/test-sets/${testSetId}/runs/public`, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer fini_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ruleExecutionMode: 'simulate',
      promptVersionId: '9bc3fb9f-85fd-496e-90b3-bcc80ff12d70'
    })
  });

  const run = await response.json();
  ~~~

  ~~~python Python theme={null}
  import requests

  test_set_id = "44c1f705-8e1a-4f61-8c4c-d519d37fb6b7"

  response = requests.post(
      f"https://api-prod.usefini.com/v2/test-sets/{test_set_id}/runs/public",
      headers={
          "Authorization": "Bearer fini_your_api_key",
          "Content-Type": "application/json",
      },
      json={
          "ruleExecutionMode": "simulate",
          "promptVersionId": "9bc3fb9f-85fd-496e-90b3-bcc80ff12d70",
      },
  )

  run = response.json()
  ~~~
</RequestExample>

<ResponseExample>
  ~~~json 202 Accepted theme={null}
  {
    "id": "5afd818a-a5f9-4e1b-9619-3c7191c12d9a",
    "testSetId": "44c1f705-8e1a-4f61-8c4c-d519d37fb6b7",
    "status": "running",
    "result": null,
    "createdBy": null,
    "createdAt": "2026-07-28T09:01:14.000Z",
    "updatedAt": "2026-07-28T09:01:14.000Z"
  }
  ~~~
</ResponseExample>


## Related topics

- [Overview](/en/api-reference/test-sets.md)
- [Quickstart](/en/quickstart.md)
- [Fini Scout](/en/fini-scout.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.