# Audit events API

The audit events API endpoint lets you retrieve audit log events for your organization.

> 📘 Enterprise plan feature
> The audit log is only available to Buildkite customers on the [Enterprise](https://buildkite.com/pricing) plan, and is only accessible to Buildkite organization administrators.

Audit events are system-generated records of activity within a Buildkite organization. The API provides read-only access. You cannot create or modify audit events using the API.

The audit events API requires the `read_audit_events` [OAuth scope](/docs/apis/managing-api-tokens#token-scopes).

## List audit events

Returns a [paginated list](/docs/rest-api#pagination) of audit events for an organization, ordered from newest to oldest.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/audit_events"
```

```json
[
  {
    "uuid": "0191e71a-552b-7be5-8a3d-8e0fc2c84e52",
    "graphql_id": "QXVkaXRFdmVudC0tLTAxOTFlNzFhLTU1MmItN2JlNS04YTNkLThlMGZjMmM4NGU1Mg==",
    "type": "OrganizationUpdatedEvent",
    "occurred_at": "2024-11-12T09:15:04.000Z",
    "actor": {
      "type": "User",
      "uuid": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
      "name": "Sam Kim"
    },
    "subject": {
      "type": "Organization",
      "uuid": "bb3125de-4dc9-44cf-ad18-65d2b71a5a34",
      "name": "acme-inc"
    },
    "context": {
      "type": "WebContext",
      "request_ip": "192.0.2.1",
      "request_user_agent": "Mozilla/5.0"
    },
    "data": {},
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/audit_events/0191e71a-552b-7be5-8a3d-8e0fc2c84e52"
  }
]
```

Required scope: `read_audit_events`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The organization's plan does not include audit logging, or the token does not have the `read_audit_events` scope. |
| --- | --- |



## Get an audit event

Returns a single audit event by UUID.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/audit_events/{uuid}"
```

```json
{
  "uuid": "0191e71a-552b-7be5-8a3d-8e0fc2c84e52",
  "graphql_id": "QXVkaXRFdmVudC0tLTAxOTFlNzFhLTU1MmItN2JlNS04YTNkLThlMGZjMmM4NGU1Mg==",
  "type": "OrganizationUpdatedEvent",
  "occurred_at": "2024-11-12T09:15:04.000Z",
  "actor": {
    "type": "User",
    "uuid": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "name": "Sam Kim"
  },
  "subject": {
    "type": "Organization",
    "uuid": "bb3125de-4dc9-44cf-ad18-65d2b71a5a34",
    "name": "acme-inc"
  },
  "context": {
    "type": "WebContext",
    "request_ip": "192.0.2.1",
    "request_user_agent": "Mozilla/5.0"
  },
  "data": {},
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/audit_events/0191e71a-552b-7be5-8a3d-8e0fc2c84e52"
}
```

Required scope: `read_audit_events`

Success response: `200 OK`

Error responses:



| `404 Not Found` | The audit event UUID does not exist or belongs to a different organization. |
| --- | --- |



## Response fields



| `uuid` | UUID of the audit event. |
| --- | --- |
| `graphql_id` | The GraphQL ID of the audit event. Use this to look up the event using the [GraphQL API](/docs/apis/graphql-api). |
| `type` | The event type, in class-style form (for example, `OrganizationUpdatedEvent`). See [logged events](/docs/platform/audit-log#logged-events) for the full set of activities that are recorded. That list uses the audit log search names (for example, `ORGANIZATION_UPDATED`), which are the uppercase, underscore-separated form of each type value with the `Event` suffix removed. |
| `occurred_at` | ISO 8601 timestamp of when the event occurred. |
| `actor` | The entity that triggered the event. Contains `type`, `uuid`, and `name`. May be `null` for system-generated events. |
| `subject` | The entity the event acted upon. Contains `type`, `uuid`, and `name`. |
| `context` | Request context for the event. Contains `type` and additional fields depending on the context type, such as `request_ip`, `request_user_agent`, or agent connection details. May be `null`. |
| `data` | Event-specific data. The structure varies by event type. |
| `url` | The canonical API URL for this audit event. |