# List audit events [API catalog](/reference/api/) · [AI Governance Audit Logs overview](/reference/api/ai-governance-audit-logs/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes/governance/audit/) · [OpenAPI specification](/reference/api/ai-governance-audit-logs/api.yaml) API version: 1 `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](/reference/api/ai-governance-audit-logs/latest/#authentication) Server: `https://api.docker.com` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "bearerAuth": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console 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' ``` ## Parameters ### org_name Location: path. Required: yes. Organization name. The value must match the organization associated with the OAT. ```json { "description": "Organization name. The value must match the organization associated with the OAT.", "example": "my-org", "in": "path", "name": "org_name", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### from Location: query. Required: no. 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. ```json { "description": "Include events created at or after this RFC 3339 timestamp. Defaults to\n30 days before the effective `to` on the first page. Must be earlier\nthan `to`, with a range of no more than 30 days. On later pages, omit\nthis parameter or use the timestamp preserved in the page token.\n", "example": "2026-08-01T00:00:00Z", "in": "query", "name": "from", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/1", "required": false, "schema": { "format": "date-time", "type": "string" } } ``` ### to Location: query. Required: no. 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. ```json { "description": "Include events created at or before this RFC 3339 timestamp. Defaults\nto the request time on the first page. On later pages, omit this\nparameter or use the timestamp preserved in the page token.\n", "example": "2026-08-25T23:59:59Z", "in": "query", "name": "to", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/2", "required": false, "schema": { "format": "date-time", "type": "string" } } ``` ### audit_session_id Location: query. Required: no. Return events from this audit session. ```json { "description": "Return events from this audit session.", "example": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", "in": "query", "name": "audit_session_id", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/3", "required": false, "schema": { "type": "string" } } ``` ### username Location: query. Required: no. Return events associated with this Docker username. ```json { "description": "Return events associated with this Docker username.", "example": "jordandoe", "in": "query", "name": "username", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/4", "required": false, "schema": { "type": "string" } } ``` ### decision Location: query. Required: no. Return events with this exact audit decision value. ```json { "description": "Return events with this exact audit decision value.", "example": "AUDIT_DECISION_DENY", "in": "query", "name": "decision", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/5", "required": false, "schema": { "type": "string" } } ``` ### enforcement_mode Location: query. Required: no. Return events with this exact enforcement mode, such as `audit`, `warn`, or `enforce`. ```json { "description": "Return events with this exact enforcement mode, such as `audit`, `warn`, or `enforce`.", "example": "enforce", "in": "query", "name": "enforcement_mode", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/6", "required": false, "schema": { "type": "string" } } ``` ### action_type Location: query. Required: no. Return events with this exact action type. ```json { "description": "Return events with this exact action type.", "example": "network_egress", "in": "query", "name": "action_type", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/7", "required": false, "schema": { "type": "string" } } ``` ### query Location: query. Required: no. 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. ```json { "description": "Case-insensitive text search across username, action type, decision, and\nevent type. Uses the same default time range as other list requests.\nThe trimmed value must be between 3 and 256 bytes.\n", "example": "network", "in": "query", "name": "query", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/8", "required": false, "schema": { "maxLength": 256, "type": "string" } } ``` ### resource_id Location: query. Required: no. Case-insensitive prefix match against the resource ID in the event payload. The trimmed value must not exceed 256 bytes. ```json { "description": "Case-insensitive prefix match against the resource ID in the event payload. The trimmed value must not exceed 256 bytes.", "example": "example.com", "in": "query", "name": "resource_id", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/9", "required": false, "schema": { "maxLength": 256, "type": "string" } } ``` ### agent Location: query. Required: no. Exact match against the agent in the event payload. The trimmed value must not exceed 256 bytes. ```json { "description": "Exact match against the agent in the event payload. The trimmed value must not exceed 256 bytes.", "example": "claude", "in": "query", "name": "agent", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/10", "required": false, "schema": { "maxLength": 256, "type": "string" } } ``` ### page_size Location: query. Required: no. Number of events to return. Defaults to 25; 0 also uses the default. Values above 100 are capped at 100. Negative values are rejected. ```json { "description": "Number of events to return. Defaults to 25; 0 also uses the default.\nValues above 100 are capped at 100. Negative values are rejected.\n", "example": 25, "in": "query", "name": "page_size", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/11", "required": false, "schema": { "default": 25, "format": "int32", "maximum": 2147483647, "minimum": 0, "type": "integer" } } ``` ### page_token Location: query. Required: no. Opaque cursor from `next_page_token` in the previous response. Preserves the resolved time range; pass it unchanged. ```json { "description": "Opaque cursor from `next_page_token` in the previous response. Preserves the resolved time range; pass it unchanged.", "in": "query", "name": "page_token", "pointer": "/paths/~1v2~1auditlogs~1governance~1{org_name}/get/parameters/12", "required": false, "schema": { "type": "string" } } ``` ## Request and responses ### Response 200 application/json Paginated audit events. Schema: ```json { "$ref": "#/components/schemas/ListAuditEventsResponse" } ``` default: ```json { "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" } ``` ### Response 400 application/json Invalid timestamp, page size, page token, filter, or search window. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": "invalid argument: from must be RFC3339" } ``` ### Response 401 application/json Missing, malformed, invalid, or expired OAT. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": "invalid or expired token" } ``` ### Response 403 application/json The OAT lacks permission, lacks organization identity, or belongs to another organization. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": "insufficient permissions" } ``` ### Response 408 application/json Request deadline exceeded. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` Example: ```json { "error": "request deadline exceeded" } ``` ### Response 429 application/json 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. Schema: ```json { "anyOf": [ { "$ref": "#/components/schemas/ApplicationRateLimitError" }, { "$ref": "#/components/schemas/Error" } ] } ``` Headers: ```json { "Retry-After": { "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" } } } ``` application: ```json { "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 application/json Unexpected server error. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` default: ```json { "error": "internal error" } ``` ### Response 503 application/json 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. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` searchTimeout: ```json { "error": "search timed out; try a narrower time range or simpler query" } ``` storeUnavailable: ```json { "error": "service temporarily unavailable" } ``` ## Complete operation contract ```json { "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" ] } ``` ## Referenced schemas - `#/components/parameters/ActionType` - `#/components/parameters/Agent` - `#/components/parameters/AuditSessionID` - `#/components/parameters/Decision` - `#/components/parameters/EnforcementMode` - `#/components/parameters/From` - `#/components/parameters/OrgName` - `#/components/parameters/PageSize` - `#/components/parameters/PageToken` - `#/components/parameters/Query` - `#/components/parameters/ResourceID` - `#/components/parameters/To` - `#/components/parameters/Username` - `#/components/responses/BadRequest` - `#/components/responses/Forbidden` - `#/components/responses/InternalError` - `#/components/responses/RateLimited` - `#/components/responses/RequestTimeout` - `#/components/responses/ServiceUnavailable` - `#/components/responses/Unauthenticated` - [#/components/schemas/ListAuditEventsResponse](/reference/api/ai-governance-audit-logs/latest/schemas/ListAuditEventsResponse/)