---
title: "Agent-safety numbers: received, evaluated, verdicts, held, released"
method: GET
path: "/inbound/stats"
tags: ["Inbound"]
---

# Agent-safety numbers: received, evaluated, verdicts, held, released

`GET /inbound/stats`

## Request

- Base URL: `https://api.oveyon.com/v1`
- URL: `https://api.oveyon.com/v1/inbound/stats`
- Auth: HTTP bearer

The same numbers the panel card shows, by day or by recipient, over a window of up to 92 days (default: the last 30). A message to two mailboxes counts once per day and once per recipient. The engine canary never enters these numbers.

## Query parameters

- `group_by` 'day' | 'recipient'
- `from` string
- `to` string

## Response `200`

Series

- InboundStats
  - `from` string, date-time
  - `to` string, date-time
  - `groupBy` 'day' | 'recipient'
  - `data` InboundStatsRow[]
    - `day` string: group_by=day
    - `recipient` string: group_by=recipient
    - `received` integer
    - `evaluated` integer: Messages with an agent-safety verdict (received minus the ones the engine could not judge).
    - `clean` integer
    - `suspicious` integer
    - `dangerous` integer
    - `quarantined` integer: Held at arrival by the agent-safety verdict in the window (holds by your inbound policies are in the policy feed, not here).
    - `released` integer: Verdict holds released by a human in the window.

## Other responses

- `400`: Invalid request — fix it before retrying. Includes `invalid_json`: with `Content-Type: application/json` the body must be valid JSON and cannot be empty; and `request_too_complex` (with `limit`): the body has a list of more than 10,000 items, more than 60,000 values in total, more than 64 levels of nesting or a number/literal longer than 32 characters — text does not count, so a large attachment is one value. An address outside ASCII (accents, a full-width @, a control character, an international domain not in xn-- form) is refused here with `reason: address_not_ascii` and the `field` it came in (`error` stays the family of that field: `bad_recipient` for to/cc/bcc, `invalid_email` for contacts, `bad_request` otherwise).
- `401`: Missing or invalid API key.
- `403`: Insufficient scope (`insufficient_scope`, with `required` and `have`), a scope the key holds but cannot use while its human-approval lock is on (`scope_blocked_by_approval_lock`, with `required` — approve:holds, write:send-policies, manage:webhooks, write:inbound, write:templates, write:surveys, write:domains, write:contacts), API key switched off by its owner in the panel (`key_disabled` — the key is valid; turn it back on or use another one, do not rotate), sending disabled, account suspended (`account_suspended`) or unknown (`account_unknown`), or the key used from an IP outside its allowed ranges (`ip_not_allowed`, with the `allowed` list — see /v1/credentials/ip-rules). 403 is not a limit: do not retry.
- `429`: Per-key limit (`rate_limited`, 600 requests/min by default per API key — or per MCP OAuth connection —, from any IP), per-IP limit for requests WITHOUT a valid credential (`rate_limited`, 600/min by default), too many unknown or malformed credentials from your address (`too_many_auth_failures`, 20/min by default, counted per IPv4 address or per IPv6 /48; a missing `Authorization`, an expired OAuth token or a disabled key do not count, and anything without the shape of one of our keys counts without being checked; from an address over that limit a valid key still gets through within 120 credential checks/min, and above them every credential not validated in the last 5 minutes gets this 429 until the minute turns) — all checked before the route, on every operation —, account quota (`quota_exceeded` with `window`, `used`, `limit`), warmup cap (`warmup_cap_reached`) or saturation (`queue_full`). Honor `Retry-After` with exponential backoff and jitter.
- `500`: internal_error — an unexpected failure on our side. The detail stays in our logs, never in the body. Retry reads; retry a write only when it is idempotent or carries an idempotency key.
- `503`: ip_rules_unavailable — the IP ranges bound to your key could not be checked right now (caution, not a denial). Retry after `Retry-After` (30 s).

---

[API](https://skmtc.dev/oveyon/apis/oveyon-api.md) · [All operations](https://skmtc.dev/oveyon/apis/oveyon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oveyon/apis/oveyon-api/revisions/abf64c09d297?raw)