API version Product manual Download OpenAPI specification Markdown

List audit events

GET/v2/auditlogs/governance/{org_name}

Returns audit events for the organization in reverse chronological order. Pass next_page_token from one response as page_token in the next request to continue listing events.

Every request covers a time range of 30 days or less. If to is omitted, it defaults to the request time. If from is omitted, it defaults to 30 days before to. from must be earlier than to. Text search uses the same defaults and requires at least three bytes after trimming whitespace.

The page token preserves the resolved time range. Keep other filters unchanged on later pages. Omit from and to or supply timestamps that match the token's range.

Connection and access

API connection and authentication guidance

https://api.docker.com

Use one of these alternatives. Requirements within an alternative apply together.

bearerAuth

Parameters

`org_name` path Required

Organization name. The value must match the organization associated with the OAT.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`from` query

Include events created at or after this RFC 3339 timestamp. Defaults to 30 days before the effective to on the first page. Must be earlier than to, with a range of no more than 30 days. On later pages, omit this parameter or use the timestamp preserved in the page token.

Type: string

All schema constraints and annotations

{
  "format": "date-time",
  "type": "string"
}

`to` query

Include events created at or before this RFC 3339 timestamp. Defaults to the request time on the first page. On later pages, omit this parameter or use the timestamp preserved in the page token.

Type: string

All schema constraints and annotations

{
  "format": "date-time",
  "type": "string"
}

`audit_session_id` query

Return events from this audit session.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`username` query

Return events associated with this Docker username.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`decision` query

Return events with this exact audit decision value.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`enforcement_mode` query

Return events with this exact enforcement mode, such as audit, warn, or enforce.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`action_type` query

Return events with this exact action type.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

`query` query

Case-insensitive text search across username, action type, decision, and event type. Uses the same default time range as other list requests. The trimmed value must be between 3 and 256 bytes.

Type: string

All schema constraints and annotations

{
  "maxLength": 256,
  "type": "string"
}

`resource_id` query

Case-insensitive prefix match against the resource ID in the event payload. The trimmed value must not exceed 256 bytes.

Type: string

All schema constraints and annotations

{
  "maxLength": 256,
  "type": "string"
}

`agent` query

Exact match against the agent in the event payload. The trimmed value must not exceed 256 bytes.

Type: string

All schema constraints and annotations

{
  "maxLength": 256,
  "type": "string"
}

`page_size` query

Number of events to return. Defaults to 25; 0 also uses the default. Values above 100 are capped at 100. Negative values are rejected.

Type: integer

All schema constraints and annotations

{
  "default": 25,
  "format": "int32",
  "maximum": 2147483647,
  "minimum": 0,
  "type": "integer"
}

`page_token` query

Opaque cursor from next_page_token in the previous response. Preserves the resolved time range; pass it unchanged.

Type: string

All schema constraints and annotations

{
  "type": "string"
}

Example

{
  "error": "request deadline exceeded"
}

Response `429`

The organization or source IP address exceeded a request limit. Application responses include the configured quota, window, and stable error code. Gateway responses can use a different body and omit these fields. Honor Retry-After when present; otherwise use exponential backoff.

application/json

Headers

Retry-After

Seconds to wait before retrying. Application responses include this header when the reset time is known, rounded up to whole seconds. It matches `retry_after_seconds`. Gateway responses can omit this header.

{
  "description": "Seconds to wait before retrying. Application responses include\nthis header when the reset time is known, rounded up to whole\nseconds. It matches `retry_after_seconds`. Gateway responses can\nomit this header.\n",
  "schema": {
    "minimum": 1,
    "type": "integer"
  }
}

One or more alternatives must match

Schema: ApplicationRateLimitError

Schema: Error

All schema constraints and annotations

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/ApplicationRateLimitError"
    },
    {
      "$ref": "#/components/schemas/Error"
    }
  ]
}

application

{
  "code": "rate_limit_exceeded",
  "error": "Your organization has reached the audit API request limit. This quota is shared across all clients and tokens in your organization; each pagination request counts. Request limit: 5 per 1 seconds. Retry after 1 seconds.",
  "limit": 5,
  "policy": "audit_governance",
  "retry_after_seconds": 1,
  "scope": "organization",
  "window_seconds": 1
}

Response `500`

Unexpected server error.

application/json

Schema: Error

default

{
  "error": "internal error"
}

Response `503`

The audit store or an authentication dependency is unavailable, or the search timed out. Retry with exponential backoff. For a search timeout, use a narrower time range or a simpler query.

application/json

Schema: Error

Example

searchTimeout

{
  "error": "search timed out; try a narrower time range or simpler query"
}

storeUnavailable

{
  "error": "service temporarily unavailable"
}

Referenced schemas

#/components/schemas/ListAuditEventsResponse

Complete operation contract

{
  "description": "Returns audit events for the organization in reverse chronological\norder. Pass `next_page_token` from one response as `page_token` in the\nnext request to continue listing events.\n\nEvery request covers a time range of 30 days or less. If `to` is\nomitted, it defaults to the request time. If `from` is omitted, it\ndefaults to 30 days before `to`. `from` must be earlier than `to`.\nText search uses the same defaults and requires at least three\nbytes after trimming whitespace.\n\nThe page token preserves the resolved time range. Keep other filters\nunchanged on later pages. Omit `from` and `to` or supply timestamps that\nmatch the token's range.\n",
  "operationId": "listAuditEvents",
  "parameters": [
    {
      "$ref": "#/components/parameters/OrgName"
    },
    {
      "$ref": "#/components/parameters/From"
    },
    {
      "$ref": "#/components/parameters/To"
    },
    {
      "$ref": "#/components/parameters/AuditSessionID"
    },
    {
      "$ref": "#/components/parameters/Username"
    },
    {
      "$ref": "#/components/parameters/Decision"
    },
    {
      "$ref": "#/components/parameters/EnforcementMode"
    },
    {
      "$ref": "#/components/parameters/ActionType"
    },
    {
      "$ref": "#/components/parameters/Query"
    },
    {
      "$ref": "#/components/parameters/ResourceID"
    },
    {
      "$ref": "#/components/parameters/Agent"
    },
    {
      "$ref": "#/components/parameters/PageSize"
    },
    {
      "$ref": "#/components/parameters/PageToken"
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "examples": {
            "default": {
              "value": {
                "events": [
                  {
                    "action_type": "network_egress",
                    "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80",
                    "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578",
                    "category": "AUDIT_CATEGORY_EVALUATION",
                    "created_at": "2026-08-25T18:42:31.123Z",
                    "decision": "AUDIT_DECISION_DENY",
                    "enforcement_mode": "enforce",
                    "event_type": "docker.marlin.audit.event.v1.AuditRecord",
                    "ingested_at": "2026-08-25T18:42:31.456Z",
                    "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
                    "payload": {
                      "agent": "claude",
                      "network_egress": {
                        "protocol": "tcp"
                      },
                      "resource_id": "example.com:443"
                    },
                    "username": "jordandoe"
                  }
                ],
                "next_page_token": "eyJ0cyI6IjIwMjYtMDgtMjVUMTg6NDI6MzEuMTIzWiIsImVpZCI6Ijk1ZTcyNTdmLTkzYzktNGYyOS1iZGU3LTg4ODMwZTJkYWU4MCIsImZyb20iOiIyMDI2LTA4LTAxVDAwOjAwOjAwWiIsInRvIjoiMjAyNi0wOC0yNVQyMzo1OTo1OVoifQ"
              }
            }
          },
          "schema": {
            "$ref": "#/components/schemas/ListAuditEventsResponse"
          }
        }
      },
      "description": "Paginated audit events."
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthenticated"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "408": {
      "$ref": "#/components/responses/RequestTimeout"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "503": {
      "$ref": "#/components/responses/ServiceUnavailable"
    }
  },
  "summary": "List audit events",
  "tags": [
    "audit-events"
  ]
}

Example request

Shell

Replace placeholders and supply the required credentials or request body.

curl \
  --request GET \
  --header "Authorization: Bearer ${TOKEN}" \
  --header 'Accept: application/json' \
  'https://api.docker.com/v2/auditlogs/governance/my-org?from=2026-08-01T00%3A00%3A00Z&to=2026-08-25T23%3A59%3A59Z&audit_session_id=8a3bc076-79d0-4502-baf3-cc6ad35fb578&username=jordandoe&decision=AUDIT_DECISION_DENY&enforcement_mode=enforce&action_type=network_egress&query=network&resource_id=example.com&agent=claude&page_size=25'

What can I help you with?

List audit events

Connection and access

Parameters

org_name path Required

from query

to query

audit_session_id query

username query

decision query

enforcement_mode query

action_type query

query query

resource_id query

agent query

page_size query

page_token query

Request and responses

Response 200

default

Response 400

default

Response 401

default

Response 403

default

Response 408

Example

Response 429

Headers

application

Response 500

default

Response 503

searchTimeout

storeUnavailable

Referenced schemas

`org_name` path Required

`from` query

`to` query

`audit_session_id` query

`username` query

`decision` query

`enforcement_mode` query

`action_type` query

`query` query

`resource_id` query

`agent` query

`page_size` query

`page_token` query

Response `200`

Response `400`

Response `401`

Response `403`

Response `408`

Response `429`

Response `500`

Response `503`