Chanl

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

idstringrequired

The scenario ID (e.g., scenario_abc123).

Parameters

variablesobject

Key-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

StatusCodeDescription
400validation_errorInvalid variable overrides or scenario is not in a runnable state
401unauthorizedMissing or invalid access token
404not_foundScenario not found
422invalid_configScenario configuration is incomplete (run validate first)
429rate_limitedConcurrent execution limit reached

On this page