> ## 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 run
> Queue an asynchronous run with optional draft configuration.
Queue an asynchronous run with optional draft configuration.
Select 1 to 200 effective cases. With no selectors, all active cases for the agent are selected, subject to the limit. Every case needs criteria. Group runs evaluate only the selected group's checks. Runs use recorded or mock Action responses and never call live Actions; selected drafts are not published. Queue failures return `503`.
## Headers
Bearer token containing your workspace API key. The key needs `write` scope.
## Body parameters
Agent UUID. The agent must belong to the workspace.
Up to 200 case UUIDs. Omit to select cases through the other selectors.
Up to 200 collection UUIDs. Their direct and group-linked cases are included.
Run only this group's shared criteria. Cannot be combined with nonempty `folderIds`.
Collection UUID for selection/origin. Every selected case must belong to it. A group must be linked to that collection.
Behavior version UUID for this agent. Omit to use the current published version.
Up to 100 unique draft rule-version UUIDs. Select at most one draft per rule.
Up to 100 unique draft article UUIDs available to this agent. Select at most one draft per original article.
## Response
Returns the run with queued case items and `202 Accepted`. New runs intentionally have an empty array of collection origins.
```bash cURL theme={null}
curl --request POST \
--url 'https://api-prod.usefini.com/v2/test-suite/runs/public' \
--header 'Authorization: Bearer fini_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"botId": "00000000-0000-4000-8000-000000000001",
"caseIds": [
"00000000-0000-4000-8000-000000000002"
],
"promptVersionId": "00000000-0000-4000-8000-000000000007",
"ruleVersionIds": [
"00000000-0000-4000-8000-000000000008"
],
"knowledgeArticleDraftIds": [
"00000000-0000-4000-8000-000000000009"
]
}'
```
```javascript Node.js theme={null}
const body = {
"botId": "00000000-0000-4000-8000-000000000001",
"caseIds": [
"00000000-0000-4000-8000-000000000002"
],
"promptVersionId": "00000000-0000-4000-8000-000000000007",
"ruleVersionIds": [
"00000000-0000-4000-8000-000000000008"
],
"knowledgeArticleDraftIds": [
"00000000-0000-4000-8000-000000000009"
]
};
const response = await fetch("https://api-prod.usefini.com/v2/test-suite/runs/public", {
method: "POST",
headers: {
Authorization: "Bearer fini_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
```
```python Python theme={null}
import requests
import json
body = json.loads('''
{
"botId": "00000000-0000-4000-8000-000000000001",
"caseIds": [
"00000000-0000-4000-8000-000000000002"
],
"promptVersionId": "00000000-0000-4000-8000-000000000007",
"ruleVersionIds": [
"00000000-0000-4000-8000-000000000008"
],
"knowledgeArticleDraftIds": [
"00000000-0000-4000-8000-000000000009"
]
}
''')
response = requests.request(
"POST",
"https://api-prod.usefini.com/v2/test-suite/runs/public",
headers={"Authorization": "Bearer fini_your_api_key"},
json=body,
)
response.raise_for_status()
result = response.json()
```
```json 202 Accepted theme={null}
{
"id": "00000000-0000-4000-8000-000000000015",
"companyId": "00000000-0000-4000-8000-000000000011",
"botId": "00000000-0000-4000-8000-000000000001",
"environment": {
"promptVersionId": "00000000-0000-4000-8000-000000000007",
"ruleVersionIds": ["00000000-0000-4000-8000-000000000008"],
"knowledgeArticleDraftIds": ["00000000-0000-4000-8000-000000000009"],
"configuration": {
"behaviour": {"id": "00000000-0000-4000-8000-000000000007", "name": "Version 2", "versionNumber": 2, "status": "DRAFT"},
"rules": [
{
"id": "00000000-0000-4000-8000-000000000008",
"ruleId": "00000000-0000-4000-8000-000000000005",
"name": "Refund workflow",
"versionNumber": 2
}
],
"articles": [
{
"id": "00000000-0000-4000-8000-000000000009",
"name": "Refund policy",
"originalArticleId": "00000000-0000-4000-8000-000000000020"
}
]
}
},
"criteriaGroupId": null,
"criteriaGroupName": null,
"createdAt": "2026-10-12T10:00:00.000Z",
"collections": [],
"items": [
{
"id": "00000000-0000-4000-8000-000000000013",
"caseId": "00000000-0000-4000-8000-000000000002",
"status": "completed",
"name": "Refund policy",
"criteria": [
{
"id": "2995012b-d9bf-58e9-c6c7-672205196681",
"companyId": "00000000-0000-4000-8000-000000000011",
"defaultCriterionId": null,
"name": "No handoff",
"type": "deterministic",
"condition": {
"scope": "SCALAR",
"predicate": {"left": {"path": "escalated", "dataType": "boolean"}, "operator": "==", "right": {"value": false}}
},
"blocking": true,
"judgePrompt": null,
"passPrompt": null,
"failPrompt": null,
"isActive": true,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
},
{
"id": "00000000-0000-4000-8000-000000000012",
"companyId": "00000000-0000-4000-8000-000000000011",
"defaultCriterionId": null,
"name": "No handoff",
"type": "deterministic",
"condition": {
"scope": "SCALAR",
"predicate": {"left": {"path": "escalated", "dataType": "boolean"}, "operator": "==", "right": {"value": false}}
},
"blocking": true,
"judgePrompt": null,
"passPrompt": null,
"failPrompt": null,
"isActive": true,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
}
],
"criteriaGroup": {
"id": "00000000-0000-4000-8000-000000000003",
"companyId": "00000000-0000-4000-8000-000000000011",
"botId": "00000000-0000-4000-8000-000000000001",
"name": "Refund checks",
"criteria": [
{
"id": "00000000-0000-4000-8000-000000000012",
"companyId": "00000000-0000-4000-8000-000000000011",
"defaultCriterionId": null,
"name": "No handoff",
"type": "deterministic",
"condition": {
"scope": "SCALAR",
"predicate": {"left": {"path": "escalated", "dataType": "boolean"}, "operator": "==", "right": {"value": false}}
},
"blocking": true,
"judgePrompt": null,
"passPrompt": null,
"failPrompt": null,
"isActive": true,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
}
],
"revision": 1,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
},
"criteriaGroups": [
{
"id": "00000000-0000-4000-8000-000000000003",
"companyId": "00000000-0000-4000-8000-000000000011",
"botId": "00000000-0000-4000-8000-000000000001",
"name": "Refund checks",
"criteria": [
{
"id": "00000000-0000-4000-8000-000000000012",
"companyId": "00000000-0000-4000-8000-000000000011",
"defaultCriterionId": null,
"name": "No handoff",
"type": "deterministic",
"condition": {
"scope": "SCALAR",
"predicate": {"left": {"path": "escalated", "dataType": "boolean"}, "operator": "==", "right": {"value": false}}
},
"blocking": true,
"judgePrompt": null,
"passPrompt": null,
"failPrompt": null,
"isActive": true,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
}
],
"revision": 1,
"createdAt": "2026-10-12T10:00:00.000Z",
"updatedAt": "2026-10-12T10:00:00.000Z"
}
],
"criterionOrigins": {
"2995012b-d9bf-58e9-c6c7-672205196681": {"groupId": "00000000-0000-4000-8000-000000000003", "groupName": "Refund checks"}
},
"result": {
"verdict": "pass",
"replayInteractionId": "00000000-0000-4000-8000-000000000030",
"criteriaResults": [
{
"criteriaId": "2995012b-d9bf-58e9-c6c7-672205196681",
"name": "No handoff",
"type": "deterministic",
"blocking": true,
"result": "pass",
"reasoning": "The deterministic condition matched.",
"evidence": ["escalated=false"]
},
{
"criteriaId": "00000000-0000-4000-8000-000000000012",
"name": "No handoff",
"type": "deterministic",
"blocking": true,
"result": "pass",
"reasoning": "The deterministic condition matched.",
"evidence": ["escalated=false"]
}
],
"environment": {
"promptVersionId": "00000000-0000-4000-8000-000000000007",
"ruleVersionIds": ["00000000-0000-4000-8000-000000000008"],
"knowledgeArticleDraftIds": ["00000000-0000-4000-8000-000000000009"],
"configuration": {
"behaviour": {
"id": "00000000-0000-4000-8000-000000000007",
"name": "Version 2",
"versionNumber": 2,
"status": "DRAFT"
},
"rules": [
{
"id": "00000000-0000-4000-8000-000000000008",
"ruleId": "00000000-0000-4000-8000-000000000005",
"name": "Refund workflow",
"versionNumber": 2
}
],
"articles": [
{
"id": "00000000-0000-4000-8000-000000000009",
"name": "Refund policy",
"originalArticleId": "00000000-0000-4000-8000-000000000020"
}
]
}
},
"messages": [
{"id": "00000000-0000-4000-8000-000000000010", "role": "user", "content": "Am I eligible for a refund?"},
{"id": "00000000-0000-4000-8000-000000000031", "role": "finibot", "content": "Your order is eligible."}
],
"actions": [
{
"name": "Check eligibility",
"toolId": "00000000-0000-4000-8000-000000000006",
"turn": 1,
"success": true,
"source": "recorded",
"output": {"eligible": true}
}
]
},
"error": null,
"createdAt": "2026-10-12T10:00:00.000Z",
"previousResult": null,
"previousCreatedAt": null,
"sameSetup": null
}
],
"createdBy": null
}
```
## Related topics
- [Get run configuration](/en/api-reference/get-test-suite-run-configuration.md)
- [Overview](/en/api-reference/test-suite.md)
- [Best practices for testing your agent](/en/testing/best-practices.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.