Audit events API

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

The audit log is only available to Buildkite customers on the Enterprise 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.

List audit events

Returns a paginated list of audit events for an organization, ordered from newest to oldest.

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

{
  "items": [
    {
      "uuid": "01931fa7-b1c0-7abc-8abc-0123456789ab",
      "graphql_id": "QXVkaXRFdmVudC0tLTAxOTMxZmE3LWIxYzAtN2FiYy04YWJjLTAxMjM0NTY3ODlhYg==",
      "type": "OrganizationUpdatedEvent",
      "occurred_at": "2024-11-12T09:15:04.000Z",
      "actor": {
        "type": "User",
        "uuid": "01234567-89ab-4cde-8f01-23456789abcd",
        "name": "Example User"
      },
      "subject": {
        "type": "Organization",
        "uuid": "12345678-9abc-4def-8012-3456789abcde",
        "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/01931fa7-b1c0-7abc-8abc-0123456789ab"
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/audit_events?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/audit_events?per_page=30&after=eyJvY2N1cnJlZF9hdCI6Ii4uLiJ9"
  }
}

The response body contains the following pagination fields:

items: The audit events on the current page.
links: URLs for the current page and available first, prev, and next pages. Follow these URLs instead of constructing cursors. The response also includes these links in the HTTP Link header.

Optional query string parameters:

`after`	Returns the next page after the supplied cursor. Cannot be combined with `before`.
`before`	Returns the previous page before the supplied cursor. Cannot be combined with `after`.
`per_page`	Number of results per page. Defaults to `30` and has a maximum of `100`.

Required scope: read_audit_events

Success response: 200 OK

Error responses:

`400 Bad Request`	The request supplies both cursor parameters, an invalid cursor, or a `per_page` value outside the supported range.
`403 Forbidden`	The organization's plan does not include audit logging, the user cannot view the audit log, or the token does not have the `read_audit_events` scope.

Get an audit event

Returns a single audit event by UUID.

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

{
  "uuid": "01931fa7-b1c0-7abc-8abc-0123456789ab",
  "graphql_id": "QXVkaXRFdmVudC0tLTAxOTMxZmE3LWIxYzAtN2FiYy04YWJjLTAxMjM0NTY3ODlhYg==",
  "type": "OrganizationUpdatedEvent",
  "occurred_at": "2024-11-12T09:15:04.000Z",
  "actor": {
    "type": "User",
    "uuid": "01234567-89ab-4cde-8f01-23456789abcd",
    "name": "Example User"
  },
  "subject": {
    "type": "Organization",
    "uuid": "12345678-9abc-4def-8012-3456789abcde",
    "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/01931fa7-b1c0-7abc-8abc-0123456789ab"
}

Required scope: read_audit_events

Success response: 200 OK

Error responses:

`403 Forbidden`	The organization's plan does not include audit logging, the user cannot view the audit log, or the token does not have the `read_audit_events` scope.
`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.
`type`	The event type, in class-style form (for example, `OrganizationUpdatedEvent`). See 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.