Output Quality API

API reference for the Output Quality Scoring admin endpoints. All endpoints require an admin JWT. See the Output Quality Scoring admin guide for feature documentation and configuration.

Base path: /api/v1/admin/quality/

Authentication: Authorization: Bearer <admin-jwt> on all requests.

---

GET /api/v1/admin/quality/metrics

Returns aggregate quality dimension scores over a time window, grouped by org, model, or provider.

Query Parameters

Parameter	Type	Default	Description
period	string	week	Time window. One of day, week, month.
date_from	ISO date	—	Start of custom date range (overrides period when combined with date_to).
date_to	ISO date	—	End of custom date range.
group_by	string	model	Grouping dimension. One of org, model, provider.

When date_from and date_to are both provided, period is ignored.

Response

{
  "entries": [
    {
      "group_value": "gpt-4o",
      "event_count": 1234,
      "avg_hallucination": 0.82,
      "avg_relevance": 0.91,
      "avg_toxicity": 0.97,
      "avg_groundedness": 0.78
    },
    {
      "group_value": "claude-3-5-sonnet",
      "event_count": 876,
      "avg_hallucination": 0.88,
      "avg_relevance": 0.89,
      "avg_toxicity": 0.99,
      "avg_groundedness": 0.85
    }
  ]
}

Entries with zero scored events in the requested window are omitted. Averages are computed only over events where scoring completed (skipped events are excluded).

Example

# Weekly metrics grouped by model (default)
curl -G https://api.arbitex.ai/api/v1/admin/quality/metrics \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data-urlencode "period=week" \
  --data-urlencode "group_by=model"

# Custom date range grouped by provider
curl -G https://api.arbitex.ai/api/v1/admin/quality/metrics \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data-urlencode "date_from=2026-03-01" \
  --data-urlencode "date_to=2026-03-31" \
  --data-urlencode "group_by=provider"

---

GET /api/v1/admin/quality/alerts

Returns threshold breach status for all four quality dimensions over the requested period. Fires the quality.threshold_breached webhook when a breach is detected.

Query Parameters

Parameter	Type	Default	Description
period	string	week	Time window to evaluate. One of day, week, month.

Threshold Configuration

Default threshold for all four metrics is 0.3 (a dimension average below 0.3 constitutes a breach). Thresholds are configurable per metric via system config keys:

Config key	Metric
quality_alert_threshold_hallucination	hallucination_score
quality_alert_threshold_relevance	relevance_score
quality_alert_threshold_toxicity	toxicity_score
quality_alert_threshold_groundedness	groundedness_score

Response

{
  "alerts": [
    {
      "metric": "groundedness",
      "threshold": 0.3,
      "current_value": 0.24,
      "group_value": "overall",
      "breached": true
    },
    {
      "metric": "hallucination",
      "threshold": 0.3,
      "current_value": 0.81,
      "group_value": "overall",
      "breached": false
    }
  ]
}

All four metrics are always returned. breached: false entries confirm the metric is within threshold. The quality.threshold_breached webhook is deduplicated per metric, period, and date — a sustained breach fires at most once per day.

Example

curl -G https://api.arbitex.ai/api/v1/admin/quality/alerts \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data-urlencode "period=week"

---

GET /api/v1/admin/quality/model-comparison

Returns per-model quality dimension averages and a composite score for a date range. Models are sorted descending by composite score.

The composite score is the unweighted mean of the four dimension averages:

composite_score = (avg_hallucination + avg_relevance + avg_toxicity + avg_groundedness) / 4

Query Parameters

Parameter	Type	Default	Description
date_from	ISO date	First day of current month	Start of comparison window.
date_to	ISO date	Current date	End of comparison window.

Response

{
  "models": [
    {
      "model_id": "claude-3-5-sonnet",
      "event_count": 876,
      "avg_hallucination": 0.88,
      "avg_relevance": 0.89,
      "avg_toxicity": 0.99,
      "avg_groundedness": 0.85,
      "composite_score": 0.9025
    },
    {
      "model_id": "gpt-4o",
      "event_count": 1234,
      "avg_hallucination": 0.82,
      "avg_relevance": 0.91,
      "avg_toxicity": 0.97,
      "avg_groundedness": 0.78,
      "composite_score": 0.8700
    }
  ]
}

Models with fewer than 10 scored events in the window are excluded to avoid statistically unreliable rankings.

Example

curl -G https://api.arbitex.ai/api/v1/admin/quality/model-comparison \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  --data-urlencode "date_from=2026-03-01" \
  --data-urlencode "date_to=2026-03-31"

---

Error Codes

Status	Code	Description
400	invalid_period	period value is not one of day, week, month.
400	invalid_date_range	date_from is after date_to, or date format is not ISO 8601.
400	invalid_group_by	group_by value is not one of org, model, provider.
401	unauthorized	Missing or invalid Authorization header.
403	forbidden	Valid token but insufficient privileges — admin role required.

Error Response Shape

{
  "error": "invalid_period",
  "message": "period must be one of: day, week, month"
}

---

Related

• Output Quality Scoring admin guide — feature overview, dimension descriptions, configuration, and alert threshold setup
• API Reference Index — full list of admin API endpoints