Events
Webhooks push events to your application as they happen. Sometimes you need to read that history on demand instead: your receiver was down and missed a delivery, you are investigating what happened to a token or a Proxy call, or you are building an events view in your own application.
The Events API returns the same event objects that Webhooks deliver, newest first, without the Webhook delivery wrapper. You can filter them by time range, event type, trace ID, and exact values inside the event payload. Use it to browse your Tenant's event history, recover missed deliveries, and follow a trace_id across related events.
Keep using Webhooks for real-time delivery. Events become searchable shortly after they occur, so a Webhook can reach you before the same event appears in search. The payload fields match what the Webhook delivers, with one exception: the network-token.created Webhook carries the single-use network token cryptogram, and the Events API never returns it.
Authentication
Send exactly one credential with each request:
| Credential | Header | Requirements |
|---|---|---|
| Application API key | BT-API-KEY: <PRIVATE_API_KEY> | A Private or Management Application with the event:read permission. The runtime-log endpoints, List Reactor Logs and List Proxy Logs, require log:read instead. |
| Basis Theory user token | Authorization: Bearer <USER_TOKEN> | A signed-in Basis Theory user's token with the same route permission plus tenant:read. The Customer Portal uses this credential. |
A request that sends both headers returns 400, even if one of them is empty or invalid. The Tenant is always taken from the credential; there is no Tenant parameter. See Authentication for how API keys are sent.
How Far Back You Can Search
Your Tenant's Log Retention quota sets how much history you can search. The default is 24 hours. Basis Theory can raise it on request up to the 30-day platform maximum; contact us to change it. A single request never reaches more than 30 days back.
The API clamps a requested time range to the visible window instead of rejecting it. A start_date earlier than your searchable history becomes the oldest visible instant, and an end_date in the future becomes the time of the request. If nothing remains after clamping, for example when the whole range is older than your retention, the response is 200 with an empty page. One request can cover your entire searchable history, so you do not need to split it into smaller ranges.
Searchable history is separate from the long-term archive Basis Theory keeps for recovery. That archive cannot be queried through the Events API.
Consistency
Indexing is asynchronous and at least once. An event can take a short time to become searchable after the operation that produced it, and a Webhook can arrive before the event appears in the Events API.
Each page suppresses repeated event IDs, so a single page never contains the same id twice. The same event can still appear on more than one page, after you restart a query, or in overlapping polling windows. Deduplicate by id.
A page with fewer results than the requested size can still have a next cursor. Keep paging until pagination.next is null.
Availability
Event search is served from the primary region of your super-region (US or EU). When the search backend in that region is unavailable, the API returns 503 instead of an empty result. There is no failover to search in a secondary region. Webhook delivery and the archive are not affected by a search outage.
Rate Limits
The standard platform rate limits apply to Events API requests. A throttled request returns 429 with a Retry-After header. There is no separate quota for the Events API.
Next Steps
- Events: the List Events endpoint, query parameters, payload filters, pagination, and errors.
- List Reactor Logs and List Proxy Logs: individual runtime-log records for one Reactor or Proxy, searchable by message.
- Webhook Event Data: the type and payload fields of every event, which are also the paths you can filter on.