Read your data
Everything the dashboard shows is available from the API with the same credentials.
List events
Section titled “List events”GET /v1/events returns events newest first, with the latest verification and screening summary for each.
| Parameter | Filters by |
|---|---|
q | Free text, matched against ids, the payee and the event’s contents |
agent_id, owner_id, payee_id | HalvorAI ids (agt_..., own_..., pye_...) |
rail | card, stripe, x402, mpp, stablecoin, bank_transfer |
status | requested, authorized, settled, failed, refunded, disputed |
verification | Verification result, for example only events with an invalid proof |
from, to | A time window, as RFC 3339 timestamps |
limit, cursor | Paging. See pagination. |
curl "https://api.sandbox.halvorai.com/v1/events?rail=x402&status=settled&limit=50" \ -H "Authorization: Bearer $HALVOR_API_KEY"Unknown query parameters are rejected with 400, so a typo never silently returns everything.
Read one event
Section titled “Read one event”GET /v1/events/{id} returns the event as received, its signature, its place in the hash chain, and its evidence items.
Evidence values can contain personal data. They are returned to API keys with events:read and to signed-in analysts,
admins and owners, and every such read is written to the audit log. Other roles see each item’s kind and digest with
redacted: true.
Agents, owners and payees
Section titled “Agents, owners and payees”| Endpoint | Returns |
|---|---|
GET /v1/agents | Agents, most recently active first, with 30-day settled payment count, spend in US cents and rails used. Filter with q and status. |
GET /v1/agents/{id} | One agent. |
GET /v1/owners, GET /v1/owners/{id} | Owners. |
GET /v1/payees, GET /v1/payees/{id} | Payees, searchable with q. |
Keys need the agents:read scope for these. Money values are strings of integer minor units, so US cents.
Headline metrics
Section titled “Headline metrics”GET /v1/metrics/overview returns the numbers a risk lead shows a sponsor bank, for a date range:
- Attribution coverage and verification coverage.
- Screening coverage.
- Alerts by detector and the false-positive rate for each.
- Median time to acknowledge an alert.
- Volume by rail.
curl "https://api.sandbox.halvorai.com/v1/metrics/overview?from=2026-10-01T00:00:00Z&to=2026-10-31T23:59:59Z" \ -H "Authorization: Bearer $HALVOR_API_KEY"Alerts, screenings, cases and packs
Section titled “Alerts, screenings, cases and packs”These have their own list and action endpoints. See detectors and alerts, sanctions screening and cases and evidence packs, or browse the API reference.
Tenant isolation
Section titled “Tenant isolation”Every request is limited to your organization. An id from another organization is simply not found: you get 404, never
403, so ids cannot be probed.