# Events API

> Things that happened in the account (also delivered to webhook endpoints).

Kept for 30 days.

| Operation | Endpoint |
|---|---|
| [List events](#listEvents) | `GET /v1/events` |
| [Retrieve an event](#retrieveEvent) | `GET /v1/events/{event}` |

## The Event object

Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days).

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the event (evt_…). |
| `object` | enum | String representing the object's type. Always "event". |
| `type` | string | Event type: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified. |
| `api_version` | string | API version used to render data.object. |
| `created` | integer | When the event happened. Unix timestamp in seconds. |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `data` | object | Event payload. |
| `data.object` | object | The object the event is about (a site, finding, scan, certificate, law_update or notice), as the API returns it. |
| `data.previous_attributes` | object | For *_changed events: the previous values of the changed fields. |
| `pending_webhooks` | integer | Webhook deliveries not yet acknowledged. |
| `request` | object | What caused the event. |
| `request.id` | string \| null | API request that caused the event (null for automatic changes). |
| `request.idempotency_key` | string \| null | Idempotency-Key of that request. |

## List events {#listEvents}

`GET /v1/events`

Events newest first. Poll with ending_before=<newest id you have> to get only new events (an alternative to webhooks).

**Scope** `events:read` · **Operation** `listEvents`

SDK: `checkbox.events.list()` (Node) · `checkbox.events.list()` (Python). MCP / agents: operation `listEvents`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `limit` | query | integer | Number of objects to return, 1-100 (default 10). |
| `starting_after` | query | string | Cursor: an object id; returns the objects after it (older). |
| `ending_before` | query | string | Cursor: an object id; returns the objects before it (newer). |
| `type` | query | string | Only this type; a trailing * matches a prefix (finding.*). |
| `created_gte` | query | integer \| null | Only events created at or after this unix time. |
| `created_lte` | query | integer \| null | Only events created at or before this unix time. |

#### Returns

Returns a list (`{ object: "list", data, has_more, url }`) of [Event](https://checkbox.site/docs/api/events#the-event-object) objects.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl -G https://app.checkbox.site/v1/events \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3
```
```node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const events = await checkbox.events.list({ limit: 3 });
console.log(events.data);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

events = checkbox.events.list(limit=3)
print(events.data)
```

```json title="Response"
{
  "object": "list",
  "data": [
    {
      "id": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "event",
      "type": "finding.created",
      "api_version": "2026-10-30",
      "created": 1793318400,
      "livemode": false,
      "data": {
        "object": {
          "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
          "object": "finding"
        },
        "previous_attributes": {
          "score": 74
        }
      },
      "pending_webhooks": 0,
      "request": {
        "id": null,
        "idempotency_key": null
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}
```

## Retrieve an event {#retrieveEvent}

`GET /v1/events/{event}`

One event with its payload (data.object) and the number of webhook deliveries still pending.

**Scope** `events:read` · **Operation** `retrieveEvent`

SDK: `checkbox.events.retrieve()` (Node) · `checkbox.events.retrieve()` (Python). MCP / agents: operation `retrieveEvent`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `event` **required** | path | string | Unique identifier of the event (evt_…). |

#### Returns

Returns an [Event](https://checkbox.site/docs/api/events#the-event-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/events/evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const event = await checkbox.events.retrieve('evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(event);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

event = checkbox.events.retrieve("evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(event)
```

```json title="Response"
{
  "id": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "event",
  "type": "finding.created",
  "api_version": "2026-10-30",
  "created": 1793318400,
  "livemode": false,
  "data": {
    "object": {
      "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "finding"
    },
    "previous_attributes": {
      "score": 74
    }
  },
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  }
}
```