Execute Scenario
Trigger an immediate simulation run for a scenario.
Execute Scenario
Queues a scenario for immediate execution. Each persona--agent pair in the scenario produces a separate simulation. Optionally override prompt variables at runtime.
Endpoint
POST /api/v1/scenarios/:id/execute
curl -X POST "https://api.chanl.ai/api/v1/scenarios/scenario_abc123/execute" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"variables": {
"charge_amount": "$49.99"
}
}'const response = await fetch('https://api.chanl.ai/api/v1/scenarios/scenario_abc123/execute', {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
variables: {
charge_amount: '$49.99',
},
}),
});
const data = await response.json();import requests
response = requests.post(
'https://api.chanl.ai/api/v1/scenarios/scenario_abc123/execute',
headers={'Authorization': f'Bearer {access_token}'},
json={
'variables': {
'charge_amount': '$49.99',
},
},
)
data = response.json()Path Parameters
idstringrequiredThe scenario ID (e.g., scenario_abc123).
Parameters
variablesobjectKey-value map of prompt variable overrides. Keys must match variable names defined in the scenario. Values not provided fall back to each variable's defaultValue.
Response
Response
{
"success": true,
"data": {
"execution": {
"id": "exec_xyz789",
"scenario_id": "scenario_abc123",
"status": "queued",
"simulations_created": 4,
"estimated_completion": "2025-03-17T10:35:00Z",
"created_at": "2025-03-17T10:30:00Z"
}
}
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | validation_error | Invalid variable overrides or scenario is not in a runnable state |
| 401 | unauthorized | Missing or invalid access token |
| 404 | not_found | Scenario not found |
| 422 | invalid_config | Scenario configuration is incomplete (run validate first) |
| 429 | rate_limited | Concurrent execution limit reached |