# Events

Docs

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](https://staging.socialtap.dev/docs/webhooks/index.md) 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.<br>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.<br>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` |  |

---

[HTML version](https://staging.socialtap.dev/docs/events/) · [Docs index for AI agents](https://staging.socialtap.dev/llms.txt) · [All docs in one file](https://staging.socialtap.dev/llms-full.txt)