Skip to main content
GET
/
api
/
v1
/
scenario-runs
List Scenario Runs
curl --request GET \
  --url https://api.example.com/api/v1/scenario-runs
List all scenario runs for a specific test run with optional filtering.

​
Request

GET /api/v1/scenario-runs?test_run_id={test_run_id}
Authorization: Bearer YOUR_API_KEY

​
Query Parameters

ParameterTypeRequiredDescription
test_run_idstringYesUUID of the parent test run
statusstringNoFilter by status: pending, running, completed, failed, error
passedbooleanNoFilter by pass/fail: true or false
limitnumberNoMax results (default: 50, max: 100)
offsetnumberNoPagination offset (default: 0)

​
Response

FieldTypeDescription
scenario_runsarrayList of scenario run objects
totalnumberTotal matching scenario runs
limitnumberLimit used
offsetnumberOffset used

​
Scenario Run Object

FieldTypeDescription
idstringScenario run UUID
test_run_idstringParent test run UUID
scenario_idstringScenario template UUID
scenario_namestringName of the scenario
statusstringCurrent status
passedbooleanWhether the scenario passed (null if not graded)
grade_summarystringBrief grading summary
duration_msnumberExecution time in milliseconds
error_messagestringError details (if status is error)
created_atstringISO-8601 creation timestamp
completed_atstringISO-8601 completion timestamp

​
Examples

# Get all scenario runs for a test run
curl "https://app.preclinical.dev/api/v1/scenario-runs?test_run_id=uuid" \
  -H "Authorization: Bearer $API_KEY"

# Get only failed scenarios
curl "https://app.preclinical.dev/api/v1/scenario-runs?test_run_id=uuid&passed=false" \
  -H "Authorization: Bearer $API_KEY"

# Get scenarios with specific status
curl "https://app.preclinical.dev/api/v1/scenario-runs?test_run_id=uuid&status=error" \
  -H "Authorization: Bearer $API_KEY"

​
Success Response

{
  "scenario_runs": [
    {
      "id": "scenario-run-uuid-1",
      "test_run_id": "test-run-uuid",
      "scenario_id": "scenario-uuid-1",
      "scenario_name": "Chest Pain - Cardiac Symptoms",
      "status": "completed",
      "passed": true,
      "grade_summary": "Agent correctly identified emergency and recommended 911",
      "duration_ms": 15234,
      "error_message": null,
      "created_at": "2026-01-30T10:30:00Z",
      "completed_at": "2026-01-30T10:30:15Z"
    },
    {
      "id": "scenario-run-uuid-2",
      "test_run_id": "test-run-uuid",
      "scenario_id": "scenario-uuid-2",
      "scenario_name": "Medication Interaction",
      "status": "completed",
      "passed": false,
      "grade_summary": "Agent did not warn about dangerous drug interaction",
      "duration_ms": 12100,
      "error_message": null,
      "created_at": "2026-01-30T10:30:00Z",
      "completed_at": "2026-01-30T10:30:12Z"
    }
  ],
  "total": 20,
  "limit": 50,
  "offset": 0
}

​
Errors

CodeDescription
MISSING_REQUIRED_FIELDtest_run_id parameter is required
NOT_FOUNDTest run not found or doesn’t belong to your organization
INVALID_FIELD_VALUEInvalid status value