Get one agent's reputation and should-send verdict
Returns one agent's live reputation: its rolling bounceRate and complaintRate recomputed from the agent's recent delivery outcomes, the current breaker state (healthy, throttled, quarantined, or review), a verdict (allow, throttle, block, review), and a shouldSend boolean that is false only when the agent is quarantined.
Returns one agent's live reputation: its rolling bounceRate and complaintRate recomputed from the agent's recent delivery outcomes, the current breaker state (healthy, throttled, quarantined, or review), a verdict (allow, throttle, block, review), and a shouldSend boolean that is false only when the agent is quarantined. The window block reports the hours (24 by default), sent, bounces, and complaints behind the rates, and thresholds echoes the warn/trip lines in force (complaintWarn 0.10% / complaintTrip 0.20%, bounceWarn 3% / bounceTrip 4%) so you never hard-code them — a rate only trips once at least 30 sends fall in the window, so a tiny sample never quarantines an agent. Poll this before a batch: a quarantined agent's sends are rejected with 429 until you clear it, while throttled tightens its send rate without blocking, and lastReason, lastTrippedAt, and lastEvaluatedAt explain the most recent transition. Automatic transitions (during a send, or when bounce and complaint feedback arrives) emit an agent.reputation.changed webhook, so you can react without polling. A never-evaluated agent reads healthy; requires the agents:read scope and returns 404 if the agent doesn't exist under your account.
Scope: agents:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | Agent UUID. |
Response
200 Success. Body: application/json, AgentReputation.
| Field | Type | Required | Description |
|---|---|---|---|
agentId | string | yes | |
state | "healthy", "throttled", "quarantined", "review" | yes | Circuit-breaker state. healthy sends freely; throttled sends under a reduced per-agent rate; quarantined is fail-closed (no send) until cleared; review is an operator-pinned hold. |
verdict | "allow", "throttle", "block", "review" | yes | |
shouldSend | boolean | yes | false only when the agent is quarantined. Poll before a batch. |
window | object | yes | |
rates | object | yes | |
thresholds | object | yes | |
lastReason | string or null | no | |
lastTrippedAt | string or null | no | |
lastEvaluatedAt | string or null | no | |
overrideLocked | boolean | no | True while an operator override lock (set in the dashboard by an owner or admin) pins the state. |
overrideLockedUntil | string (date-time) or null | no | When the override lock ends (at most 24 hours after it was set); null without a lock. |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |