---
title: "List Audit Events"
method: POST
path: "/api/audit/events"
tags: ["Audit Logs"]
---

# List Audit Events

`POST /api/audit/events`

## Request

- Base URL: `https://api.codeant.ai`
- URL: `https://api.codeant.ai/api/audit/events`
- Auth: HTTP bearer

Retrieves your organization's audit events oldest-first with cursor pagination. Designed for incremental ingestion: pass `since` (or the previous `next_cursor`) on each run to fetch only new events. Authenticate with a CodeAnt API token (requires the `settings_organization: read` permission when token scoping is configured). Every call to this endpoint is itself recorded in the audit log as `audit_log.api_read`.

## Request body

- AuditEventsRequest
  - `platform` 'github' | 'gitlab' | 'bitbucket' | 'azure_devops', required: Git platform of the organization
  - `org` string, required: Organization / workspace slug
  - `github_base_url` string: Self-hosted instance URL (also gitlab_base_url / bitbucket_base_url / azure_devops_base_url). Defaults to the cloud host.
  - `start_date` string, date: Inclusive UTC start date. Default: last 7 days; clamped to the 180-day retention window.
  - `end_date` string, date: Inclusive UTC end date. Default: today.
  - `days` integer: Alternative to explicit dates: lookback window in days (max 180).
  - `since` string, date-time: Only events STRICTLY AFTER this ISO 8601 timestamp; also defaults the range to [since, today]. Use your last consumed event's timestamp for incremental pulls.
  - `cursor` string: Opaque cursor from a previous response — resume paging after it.
  - `limit` integer: Events per page.
  - `format` 'json' | 'ndjson' | 'csv': json returns the envelope below; ndjson/csv return the raw file body with paging in X-Next-Cursor / X-Has-More headers. CSV is RFC 4180 (fields with commas, quotes or line breaks are properly quoted).

## Response `200`

Audit events retrieved successfully. With `format: ndjson` or `csv` the body is the raw file instead, and paging moves to the `X-Next-Cursor` and `X-Has-More` response headers.

- AuditEventsResponse
  - `org` string
  - `service` string
  - `base_url_domain` string
  - `start_date` string, date
  - `end_date` string, date
  - `retention_days` integer
  - `count` integer: Events in this page
  - `has_more` boolean: True when more pages match — call again with next_cursor
  - `next_cursor` string, nullable: Opaque cursor for the next page; also a durable resume point
  - `events` AuditEvent[]: Events in ascending timestamp order (oldest first)
    - `event_id` string: Immutable unique event id (32-char hex)
    - `timestamp` string, date-time: ISO 8601 UTC
    - `action` string: Stable machine action name (domain.verb)
    - `description` string: Human-readable action description
    - `actor_type` 'user' | 'system' | 'service_account' | 'integration': Never an unattributed 'unknown'
    - `actor_id` string: User sub or stable system identity
    - `actor_email` string, nullable
    - `org` string
    - `service` 'github' | 'gitlab' | 'bitbucket' | 'azuredevops'
    - `base_url_domain` string: Git platform host (self-hosted aware)
    - `source` 'ui' | 'api' | 'scheduled_job' | 'system': Channel the action came from
    - `target_type` string, nullable
    - `target_id` string, nullable
    - `target_name` string, nullable: Affected resource name/path/repository
    - `outcome` 'success' | 'denied' | 'failure'
    - `status_code` integer: HTTP status of the audited request
    - `method` string
    - `path` string
    - `ip` string
    - `user_agent` string: May contain commas or line breaks — always quoted in CSV output
    - `request_id` string: Correlation id shared with server logs
    - `changes` object, nullable: Per-field before/after values for configuration, permission and security changes. Sensitive keys are '<redacted>'.
    - `details` object, nullable: Redacted, truncated request summary. Never raw payloads, tokens or secrets.

## Other responses

- `400`: Invalid parameters (e.g. malformed `since` timestamp)
- `401`: Invalid or missing access token

## Changes

- **2026-11-03** `0eb1442ce49d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/codeant/apis/codeant-ai-api/changes/api/audit/events/post.md)

---

[API](https://skmtc.dev/codeant/apis/codeant-ai-api.md) - [All operations](https://skmtc.dev/codeant/apis/codeant-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/codeant/apis/codeant-ai-api/revisions/0eb1442ce49d?raw)