Docs

Events

Every event type, its data, and how to list and replay events: what webhooks deliver, kept for a month.

An event records something that happened in your account. Every event is kept for 30 days and listed by GET /v1/events, whether or not a webhook endpoint received it, and each one is delivered to the webhook endpoints subscribed to its type.

Route	What it does	Key scope
`GET /v1/events`	List events, newest first	`account:read`
`GET /v1/events/{id}`	Get an event	`account:read`
`POST /v1/events/{id}/redeliver`	Deliver an event again	`admin`

The event object

The body of a webhook delivery is the event object, exactly as GET /v1/events/{id} returns it:

Field	Type	Description
`object`	`string`	Always event. One of `event`
`id`	`string`	The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.
`type`	`string`	The event type (event types table); new types may be added.
`timestamp`	`string` (date-time)	When it happened.
`data`	`any`	The type's data object (small: a summary plus links).

Event types

Type	When	data
`job.completed`	A job ended with every item ended (check request_counts: items fail individually).	`JobEventData`
`job.canceled`	A canceled job ended: its running items finished.	`JobEventData`
`job.expired`	A job reached its deadline; its unfinished items expired.	`JobEventData`
`credits.low`	A balance change took the balance from above the account's low_balance_threshold to at or below it (once per crossing; the owner is emailed too).	`CreditsLowData`
`credits.depleted`	The balance reached 0 (once, until credits are added).	`CreditsDepletedData`
`api_key.spend_limit_reached`	An API key's request (or job) was refused for its spend limit, the first time in the limit's interval.	`SpendLimitReachedData`
`webhook.test`	Sent by POST /v1/webhook_endpoints/{id}/test to that endpoint only.	`WebhookTestData`

New types may be added; ignore the ones you don't handle. Subscribe an endpoint to a family with a wildcard (job.*) or to everything with *, and filter GET /v1/events the same way with its type parameter.

Job events

job.completed, job.canceled and job.expired carry the job's summary and links, never its results:

Field	Type	Description
`object`	`string`	One of `job`
`id`	`string`
`status`	`string`	One of `queued`, `running`, `canceling`, `completed`, `canceled`, `expired`
`request_counts`	`object`
`request_counts.total`	`integer`
`request_counts.queued`	`integer`	Not started.
`request_counts.running`	`integer`	Started (fetching, waiting for a retry or walking pages).
`request_counts.succeeded`	`integer`
`request_counts.failed`	`integer`
`request_counts.canceled`	`integer`
`request_counts.expired`	`integer`
`credits`	`object`
`credits.max`	`integer`	max_credits: the most the job may spend.
`credits.reserved`	`integer`	Credits still held for items not ended (0 once the job ends).
`credits.charged`	`integer`	Credits charged so far (items' prices; failed items are free).
`metadata`	`object`
`created_at`	`string` (date-time)
`finished_at`	`string` (date-time) or `null`
`url`	`string`	GET this (with your API key) for the job.
`results_url`	`string`	GET this (with your API key) for its results.

url is the job and results_url its results, both read with your API key.

Account events

The balance and spend events come from the account itself (live keys only: test requests never touch the balance), and webhook.test from a test delivery. Their data:

`credits.low`

Field	Type	Description
`balance`	`integer`	The balance after the change that crossed the threshold.
`low_balance_threshold`	`integer`	The account's low_balance_threshold at the time.

`credits.depleted`

Field	Type	Description
`balance`	`integer`	The balance: 0.

`api_key.spend_limit_reached`

Field	Type	Description
`api_key_id`	`string`	The key (key_…) whose spend limit was reached.
`spend_limit`	`object`	Its spend limit.
`spend_limit.amount`	`integer`	Most credits the key may spend per interval.
`spend_limit.interval`	`string`	Calendar day or month, UTC. One of `day`, `month`
`used`	`integer`	Credits the key had used this interval (spent plus held by its requests in flight).
`resets_at`	`string` (date-time)	Start of the next interval, RFC 3339 UTC: the key can spend again then.

`webhook.test`

Field	Type	Description
`webhook_endpoint_id`	`string`