> ## Documentation Index > Fetch the complete documentation index at: https://docs.codeant.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Audit Events > 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`. ## OpenAPI ````yaml /openapi.json post /api/audit/events openapi: 3.0.3 info: title: CodeAnt AI API description: >- API for code analysis (SAST, SCA, secrets, IaC) and developer productivity metrics. Supports GitHub, GitLab, Bitbucket, and Azure DevOps. version: 1.0.0 servers: - url: https://api.codeant.ai description: Production server security: [] tags: - name: Analysis description: Code analysis operations - name: Agent Analysis description: >- AI-powered agent analysis operations. Uses LLM-based code exploration agents to perform deep security threat hunting, bug finding, and custom analysis with reflection-based false positive filtering. - name: Developer Metrics - Teams description: >- Manage developer teams: create, update, delete teams and manage team membership. Teams are used to organize developers and scope metrics. - name: Developer Metrics description: >- Developer productivity and activity metrics: active developers, PR throughput, individual comparisons, and AI-generated summaries. All endpoints support GitHub, GitLab, Bitbucket, and Azure DevOps. - name: Audit Logs description: >- Read-only access to your organization's audit trail for compliance, ETL and SIEM ingestion. Events are immutable, retained for 180 days, and cover security-relevant actions: user management, access control, credentials, scan triggers, configuration changes and data exports. Secrets and tokens are redacted and never appear in any response format. paths: /api/audit/events: post: tags: - Audit Logs summary: List Audit Events description: >- 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`. operationId: listAuditEvents requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuditEventsRequest' examples: basic: summary: Last 7 days (default range) value: platform: github org: Example-Org incremental: summary: Incremental ETL pull since a timestamp value: platform: github org: Example-Org since: '2026-07-30T00:00:00Z' limit: 1000 ndjson: summary: NDJSON file for a custom range value: platform: gitlab org: example-group start_date: '2026-07-01' end_date: '2026-07-31' format: ndjson responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/AuditEventsResponse' example: org: Example-Org service: github base_url_domain: github.com start_date: '2026-07-24' end_date: '2026-07-31' retention_days: 180 count: 2 has_more: false next_cursor: Y29kZWFudC1hdWRpdC1sb2dzLzIwMjYtMDctMzAvLi4u events: - event_id: a3f9c2e1b4d84f7a9c0e5d6b7a8f9012 timestamp: '2026-07-30T09:14:03.512345Z' action: rbac.role_update description: 'Access control: role update' actor_type: user actor_id: harshit-dubey actor_email: admin@example.com org: Example-Org service: github base_url_domain: github.com source: ui target_type: rbac target_id: role_7d2f target_name: Security Reviewer outcome: success status_code: 200 method: POST path: /settings/rbac/roles/update ip: 203.0.113.42 user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) request_id: req_01J1ZX2Y3A4B5C6D changes: permissions: before: read after: write details: role_name: Security Reviewer - event_id: c1a2b3d4e5f60718293a4b5c6d7e8f90 timestamp: '2026-07-30T10:00:00.000000Z' action: analysis.scan_trigger description: 'Analysis: scan trigger' actor_type: system actor_id: codeant-internal-queue actor_email: null org: Example-Org service: github base_url_domain: github.com source: scheduled_job target_type: analysis target_id: null target_name: example-org/payments-api outcome: success status_code: 200 method: POST path: /doAnalysis ip: 10.0.4.18 user_agent: python-requests/2.32.0 request_id: req_01J1ZXB2C3D4E5F6 changes: null details: reponame: example-org/payments-api branch: main '400': description: Invalid parameters (e.g. malformed `since` timestamp) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Invalid `since` — use an ISO 8601 timestamp '401': description: Invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: >- Access token invalid or does not have access to this organization security: - BearerAuth: [] components: schemas: AuditEventsRequest: type: object required: - platform - org properties: platform: type: string enum: - github - gitlab - bitbucket - azure_devops description: Git platform of the organization org: type: string description: Organization / workspace slug github_base_url: type: string description: >- Self-hosted instance URL (also gitlab_base_url / bitbucket_base_url / azure_devops_base_url). Defaults to the cloud host. example: https://github.com start_date: type: string format: date description: >- Inclusive UTC start date. Default: last 7 days; clamped to the 180-day retention window. end_date: type: string format: date description: 'Inclusive UTC end date. Default: today.' days: type: integer description: 'Alternative to explicit dates: lookback window in days (max 180).' since: type: string format: date-time description: >- 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: type: string description: Opaque cursor from a previous response — resume paging after it. limit: type: integer default: 100 maximum: 1000 description: Events per page. format: type: string enum: - json - ndjson - csv default: json description: >- 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). AuditEventsResponse: type: object properties: org: type: string service: type: string base_url_domain: type: string start_date: type: string format: date end_date: type: string format: date retention_days: type: integer example: 180 count: type: integer description: Events in this page has_more: type: boolean description: True when more pages match — call again with next_cursor next_cursor: type: string nullable: true description: Opaque cursor for the next page; also a durable resume point events: type: array description: Events in ascending timestamp order (oldest first) items: $ref: '#/components/schemas/AuditEvent' ErrorResponse: type: object properties: error: type: string description: Error message AuditEvent: type: object properties: event_id: type: string description: Immutable unique event id (32-char hex) example: a3f9c2e1b4d84f7a9c0e5d6b7a8f9012 timestamp: type: string format: date-time description: ISO 8601 UTC example: '2026-07-30T09:14:03.512345Z' action: type: string description: Stable machine action name (domain.verb) example: rbac.role_update description: type: string description: Human-readable action description example: 'Access control: role update' actor_type: type: string enum: - user - system - service_account - integration description: Never an unattributed 'unknown' actor_id: type: string description: User sub or stable system identity example: harshit-dubey actor_email: type: string nullable: true example: admin@example.com org: type: string example: Example-Org service: type: string enum: - github - gitlab - bitbucket - azuredevops base_url_domain: type: string description: Git platform host (self-hosted aware) example: github.com source: type: string enum: - ui - api - scheduled_job - system description: Channel the action came from target_type: type: string nullable: true example: rbac target_id: type: string nullable: true example: role_7d2f target_name: type: string nullable: true description: Affected resource name/path/repository example: Security Reviewer outcome: type: string enum: - success - denied - failure status_code: type: integer description: HTTP status of the audited request example: 200 method: type: string example: POST path: type: string example: /settings/rbac/roles/update ip: type: string example: 203.0.113.42 user_agent: type: string description: May contain commas or line breaks — always quoted in CSV output request_id: type: string description: Correlation id shared with server logs changes: type: object nullable: true description: >- Per-field before/after values for configuration, permission and security changes. Sensitive keys are ''. additionalProperties: type: object properties: before: nullable: true after: nullable: true details: type: object nullable: true description: >- Redacted, truncated request summary. Never raw payloads, tokens or secrets. additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer description: >- CodeAnt API token (`cdt_...`), created on the Settings → API Tokens page. Pass via `Authorization: Bearer ` header. ````