Skip to Content
ContributeBackendTest Result Statistics

Test Result Statistics API

GET /test_results/stats aggregates test results for dashboards and reporting: per-metric and overall pass/fail rates, dimensional breakdowns, and timelines. It reads from the v_test_result_stats view, using the stored test result status (with human-review overrides applied) as the source of truth — see Test Result Status.

All requests require a bearer token:

request.sh
curl 'http://localhost:8080/test_results/stats?mode=summary&months=6' \
-H 'Authorization: Bearer YOUR_TOKEN'

Modes

The mode parameter selects which sections the response includes; every response also carries metadata. Use the narrowest mode for the job to keep payloads small.

ModeSections (besides metadata)
summaryoverall_pass_rates
overalloverall_pass_rates
metricsmetric_pass_rates
behaviorbehavior_pass_rates
categorycategory_pass_rates
topictopic_pass_rates
timelinetimeline
test_runstest_run_summary
allall of the above (default when mode is omitted)

Filters

All UUID and tag filters accept multiple values via repeated parameters (e.g. ?behavior_ids=uuid1&behavior_ids=uuid2); results match any of the given IDs. tags uses AND logic (a test must carry all listed tags).

ParameterTypeDescription
test_set_idsUUID[]Filter by test sets
test_idsUUID[]Filter by specific tests
test_type_idsUUID[]Filter by test types
behavior_idsUUID[]Filter by behaviors
category_idsUUID[]Filter by categories
topic_idsUUID[]Filter by topics
status_idsUUID[]Filter by test statuses
prompt_idsUUID[]Filter by prompts
test_run_idsUUID[]Filter by test runs (test_run_id also accepted for a single run)
user_idsUUID[]Filter by test creators
assignee_idsUUID[]Filter by assignees
owner_idsUUID[]Filter by owners
tagsstring[]Filter by tags (AND logic)
priority_min / priority_maxintPriority range (inclusive)
start_date / end_dateISO dateExplicit date range (overrides months)
monthsintHistorical window, default 6

Response shape

Each *_pass_rates block reports total, passed, failed, and pass_rate (percentage). metric_pass_rates, behavior_pass_rates, category_pass_rates, and topic_pass_rates key those blocks by name.

response.json
{
  "overall_pass_rates": {
    "total": 150,
    "passed": 75,
    "failed": 75,
    "pass_rate": 50
  },
  "metric_pass_rates": {
    "Answer Relevancy": {
      "total": 150,
      "passed": 135,
      "failed": 15,
      "pass_rate": 90
    }
  },
  "metadata": {
    "mode": "all",
    "total_test_results": 150,
    "total_test_runs": 5,
    "start_date": "2024-06-01T00:00:00+00:00",
    "end_date": "2024-12-01T00:00:00+00:00",
    "organization_id": "org-uuid",
    "available_metrics": [
      "Answer Relevancy",
      "Answer Fluency"
    ],
    "available_behaviors": [
      "Factual Accuracy",
      "Reasoning"
    ],
    "available_categories": [
      "RAG Systems",
      "Chatbots"
    ],
    "available_topics": [
      "Healthcare",
      "Finance"
    ]
  }
}

Examples

examples.sh
# Dashboard widget: overall rates only, last month
curl '.../test_results/stats?mode=summary&months=1' -H 'Authorization: Bearer TOKEN'

# 12-month metric trends for a regression suite
curl '.../test_results/stats?mode=metrics&test_set_ids=uuid&months=12' -H 'Authorization: Bearer TOKEN'

# Compare two behaviors over a date range
curl '.../test_results/stats?mode=behavior&behavior_ids=uuid1&behavior_ids=uuid2&start_date=2024-01-01&end_date=2024-06-30' -H 'Authorization: Bearer TOKEN'
Test ReviewsTest Result Status