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 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"

[
  {
    "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.

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

{
  "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.
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.