Skip to main content
GET
/
api
/
v1
/
runs
/
{id}
Get Run
curl --request GET \
  --url https://api.example.com/api/v1/runs/{id}
Get the current status and summary of a test run.

​
Endpoints

EndpointDescription
GET /api/v1/runs/{id}Get run status and summary
GET /api/v1/runs/{id}/resultsGet detailed results with scenario breakdown

​
Get Run Status

GET /api/v1/runs/{id}
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesUUID of the run

​
Response

FieldTypeDescription
idstringRun UUID
test_run_idstringHuman-readable run ID
namestringRun name
statusstringCurrent status
agent_idstringUUID of the tested agent
agent_namestringName of the tested agent
pass_ratenumberPass rate percentage (0-100)
passed_countnumberNumber of passing scenarios
failed_countnumberNumber of failing scenarios
error_countnumberNumber of errored scenarios
total_scenariosnumberTotal scenarios in run
started_atstringISO-8601 start timestamp
completed_atstringISO-8601 completion timestamp (if completed)
duration_secondsnumberRun duration in seconds (if completed)

​
Status Values

StatusDescription
pendingRun created, not yet started
runningScenarios actively executing
gradingAll conversations complete, grading in progress
completedRun finished successfully
failedRun failed due to error
canceledRun was canceled

​
Examples

curl "https://app.preclinical.dev/api/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer $API_KEY"

​
Success Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "test_run_id": "TR-00042",
  "name": "Emergency Response Test",
  "status": "completed",
  "agent_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "agent_name": "Healthcare Assistant",
  "pass_rate": 85.0,
  "passed_count": 17,
  "failed_count": 3,
  "error_count": 0,
  "total_scenarios": 20,
  "started_at": "2026-01-30T10:30:00Z",
  "completed_at": "2026-01-30T10:32:45Z",
  "duration_seconds": 165
}

​
Get Detailed Results

GET /api/v1/runs/{id}/results
Authorization: Bearer YOUR_API_KEY
Returns the run summary plus detailed results for each scenario.

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber100Max results to return (max: 500)
offsetnumber0Number of results to skip
statusstringFilter by status: passed, failed, error, pending

​
Response

Returns all fields from the summary endpoint, plus:
FieldTypeDescription
resultsarrayArray of scenario results
results_totalnumberTotal matching results
results_limitnumberLimit used
results_offsetnumberOffset used

​
Scenario Result Fields

FieldTypeDescription
idstringScenario run UUID
scenario_idstringScenario template UUID
scenario_namestringName of the scenario
statusstringpassed, failed, error, pending, running, grading
passedbooleanWhether the scenario passed grading
grade_summarystringBrief grading summary
error_messagestringError message (if errored)
duration_msnumberScenario execution time in milliseconds

​
Examples

# Get all results
curl "https://app.preclinical.dev/api/v1/runs/uuid/results" \
  -H "Authorization: Bearer $API_KEY"

# Get only failed scenarios
curl "https://app.preclinical.dev/api/v1/runs/uuid/results?status=failed" \
  -H "Authorization: Bearer $API_KEY"

# Paginate results
curl "https://app.preclinical.dev/api/v1/runs/uuid/results?limit=50&offset=50" \
  -H "Authorization: Bearer $API_KEY"

​
Success Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "test_run_id": "TR-00042",
  "name": "Emergency Response Test",
  "status": "completed",
  "agent_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "agent_name": "Healthcare Assistant",
  "pass_rate": 85.0,
  "passed_count": 17,
  "failed_count": 3,
  "error_count": 0,
  "total_scenarios": 20,
  "started_at": "2026-01-30T10:30:00Z",
  "completed_at": "2026-01-30T10:32:45Z",
  "duration_seconds": 165,
  "results": [
    {
      "id": "scenario-run-uuid-1",
      "scenario_id": "scenario-uuid-1",
      "scenario_name": "Chest Pain - Cardiac Symptoms",
      "status": "passed",
      "passed": true,
      "grade_summary": "Agent correctly identified emergency and recommended 911",
      "duration_ms": 15234
    },
    {
      "id": "scenario-run-uuid-2",
      "scenario_id": "scenario-uuid-2",
      "scenario_name": "Medication Interaction",
      "status": "failed",
      "passed": false,
      "grade_summary": "Agent did not warn about dangerous drug interaction",
      "duration_ms": 12100
    }
  ],
  "results_total": 20,
  "results_limit": 100,
  "results_offset": 0
}

​
Errors

CodeDescription
RUN_NOT_FOUNDRun not found or doesn’t belong to your organization

​
Polling Pattern

async function waitForCompletion(runId, maxWaitMs = 300000) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitMs) {
    const response = await fetch(
      `https://app.preclinical.dev/api/v1/runs/${runId}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );

    const run = await response.json();

    if (['completed', 'failed', 'canceled'].includes(run.status)) {
      return run;
    }

    // Wait 5 seconds before next poll
    await new Promise(r => setTimeout(r, 5000));
  }

  throw new Error('Timeout waiting for run completion');
}