Skip to main content
GET
/
api
/
v1
/
runs
List Runs
curl --request GET \
  --url https://api.example.com/api/v1/runs
List all test runs for your organization with optional filtering.

​
Request

GET /api/v1/runs
Authorization: Bearer YOUR_API_KEY

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber20Max results (max: 100)
offsetnumber0Pagination offset
statusstringFilter by status: pending, running, grading, completed, failed, canceled

​
Response

FieldTypeDescription
runsarrayArray of run objects
totalnumberTotal count matching filters
limitnumberLimit used
offsetnumberOffset used

​
Run Object

FieldTypeDescription
idstringRun UUID
test_run_idstringHuman-readable run ID
namestringRun name
statusstringRun status
agent_idstringUUID of the tested agent
agent_namestringName of the tested agent
pass_ratenumberPass rate percentage (0-100)
passed_countnumberPassing scenarios
failed_countnumberFailing scenarios
error_countnumberErrored scenarios
total_scenariosnumberTotal scenarios
started_atstringISO-8601 start timestamp
completed_atstringISO-8601 completion timestamp
created_atstringISO-8601 creation timestamp

​
Examples

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

# Filter by status
curl "https://app.preclinical.dev/api/v1/runs?status=completed" \
  -H "Authorization: Bearer $API_KEY"

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

​
Success Response

{
  "runs": [
    {
      "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",
      "created_at": "2026-01-30T10:29:55Z"
    },
    {
      "id": "8d0f7780-8536-51ef-055c-f18fd2g91bf8",
      "test_run_id": "TR-00041",
      "name": "Regression Test",
      "status": "completed",
      "agent_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "agent_name": "Healthcare Assistant",
      "pass_rate": 95.0,
      "passed_count": 19,
      "failed_count": 1,
      "error_count": 0,
      "total_scenarios": 20,
      "started_at": "2026-01-29T14:15:00Z",
      "completed_at": "2026-01-29T14:17:30Z",
      "created_at": "2026-01-29T14:14:50Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
Pagination

Use limit and offset to paginate through results: 
async function getAllRuns() {
  const allRuns = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://app.preclinical.dev/api/v1/runs?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );

    const data = await response.json();
    allRuns.push(...data.runs);

    if (data.runs.length < limit) {
      break; // No more results
    }

    offset += limit;
  }

  return allRuns;
}

​
Filtering Examples

​
Recent Failed Runs

curl "https://app.preclinical.dev/api/v1/runs?status=failed&limit=10" \
  -H "Authorization: Bearer $API_KEY"

​
Check for Running Runs

async function hasRunningRuns() {
  const response = await fetch(
    'https://app.preclinical.dev/api/v1/runs?status=running',
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  return data.total > 0;
}