> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List audit events
> Lists tool calls, LLM calls, anomaly signals and policy decisions, newest first. See [Audit trail](/monitor/audit-trail).
`meta.nextCursor` is set when the page is full. `meta.archive` is added when `from` and `to` overlap archived data; restore it with **Restore archived events**.
Cursors filter on `timestamp < cursor`, so they only page correctly with the default `sort=ts&dir=desc`.
**Required permission:** `audit:read`
## OpenAPI
````yaml /api-reference/openapi.yaml get /api/v1/audit-events
openapi: 3.1.0
info:
title: Igris Management API
version: '1'
description: >-
REST API for managing Igris connections, policies, sessions, audit events
and alerts.
servers:
- url: https://api.igrisecurity.com
security:
- bearerAuth: []
tags:
- name: Connections
- name: Policies
- name: Sessions
- name: Audit Events
- name: Incidents
- name: Webhooks
- name: API Keys
- name: Members
- name: LLM Providers
- name: LLM Cost
- name: Observe
paths:
/api/v1/audit-events:
get:
tags:
- Audit Events
summary: List audit events
description: >
Lists tool calls, LLM calls, anomaly signals and policy decisions,
newest first. See [Audit trail](/monitor/audit-trail).
`meta.nextCursor` is set when the page is full. `meta.archive` is added
when `from` and `to` overlap archived data; restore it with **Restore
archived events**.
Cursors filter on `timestamp < cursor`, so they only page correctly with
the default `sort=ts&dir=desc`.
**Required permission:** `audit:read`
operationId: listAuditEvents
parameters:
- name: limit
in: query
description: Page size. Default 50, max 500.
schema:
type: integer
minimum: 1
maximum: 500
default: 50
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Cursor'
- name: source
in: query
description: Event source. `all` or omitted means every source.
schema:
type: string
enum:
- all
- igris
- portkey
- helicone
- cloudflare
- cloudwatch
- datadog
- raw
- name: type
in: query
description: >-
Event type. Accepts a comma-separated list, for example
`llm_call,mcp_tool_call`.
schema:
type: string
- name: policyAction
in: query
description: >-
`allow`, `deny`, `alert` or `redact`. Accepts a comma-separated
list.
schema:
type: string
- name: connection
in: query
description: Connection slug.
schema:
type: string
- name: userId
in: query
description: Exact match.
schema:
type: string
- name: traceId
in: query
description: Exact match.
schema:
type: string
- name: sessionId
in: query
description: Exact match.
schema:
type: string
- name: from
in: query
description: ISO timestamp, inclusive lower bound.
schema:
type: string
format: date-time
- name: to
in: query
description: ISO timestamp, exclusive upper bound.
schema:
type: string
format: date-time
- name: q
in: query
description: Substring match on ID, model, tool, connection, or user.
schema:
type: string
- name: llmProvider
in: query
schema:
type: string
- name: llmModel
in: query
description: Accepts `*` wildcards, for example `gpt-4o*`.
schema:
type: string
- name: llmEndpoint
in: query
schema:
type: string
- name: deniedBy
in: query
schema:
type: string
- name: minCostCents
in: query
description: Minimum cost in cents.
schema:
type: number
- name: sort
in: query
schema:
type: string
enum:
- ts
- type
- action
- detail
default: ts
- name: dir
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
responses:
'200':
description: A page of events.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AuditEvent'
meta:
allOf:
- $ref: '#/components/schemas/CursorListMeta'
- type: object
properties:
archive:
type: object
description: >-
Present only when `from`/`to` overlap archived
data.
properties:
archivedRanges:
type: array
items:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
archiveIds:
type: array
items:
type: string
rowCount:
type: integer
byteCount:
type: integer
totalRows:
type: integer
totalBytes:
type: integer
example:
data:
- id: 1a2b3c4d-0000-4000-8000-000000000004
source: igris
type: mcp_tool_call
timestamp: '2026-01-01T00:00:00Z'
toolName: create_branch
policyAction: allow
policyId: 7b1d4c2e-0000-4000-8000-000000000002
policyName: Block delete tools
connectionSlug: github-prod
sessionId: 9c3e5f10-0000-4000-8000-000000000003
userId: alice@company.com
traceId: ig_trace_abc123
severity: null
meta:
total: 1234
limit: 50
offset: 0
nextCursor: '2026-01-01T00:00:00.000Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
parameters:
Offset:
name: offset
in: query
description: Number of rows to skip.
schema:
type: integer
minimum: 0
default: 0
Cursor:
name: cursor
in: query
description: The `meta.nextCursor` value from the previous page.
schema:
type: string
schemas:
AuditEvent:
type: object
description: >
One audit event. LLM events also carry `provider`, `model`, `tokensIn`,
`tokensOut`, `costCents`, `latencyMs`, `llmEndpoint` and `deniedBy`.
`actorKind`, `actorId` and `actorName` record who acted.
properties:
id:
type: string
format: uuid
organizationId:
type: string
source:
type: string
enum:
- igris
- portkey
- helicone
- cloudflare
- cloudwatch
- datadog
- raw
type:
type: string
enum:
- llm_call
- mcp_tool_call
- pii_redaction
- injection_blocked
- budget_exceeded
- anomaly
- connection_lifecycle
- access_change
timestamp:
type: string
format: date-time
provider:
type:
- string
- 'null'
model:
type:
- string
- 'null'
tokensIn:
type:
- integer
- 'null'
tokensOut:
type:
- integer
- 'null'
cachedInputTokens:
type:
- integer
- 'null'
costCents:
type:
- number
- 'null'
latencyMs:
type:
- integer
- 'null'
llmEndpoint:
type:
- string
- 'null'
deniedBy:
type:
- string
- 'null'
requestMode:
type:
- string
- 'null'
mcpServer:
type:
- string
- 'null'
toolName:
type:
- string
- 'null'
toolArgs:
description: Tool call arguments as JSON.
toolResult:
type:
- string
- 'null'
policyAction:
type:
- string
- 'null'
enum:
- allow
- deny
- alert
- redact
- null
policyId:
type:
- string
- 'null'
format: uuid
policyName:
type:
- string
- 'null'
sessionId:
type:
- string
- 'null'
piiEntitiesFound:
type:
- array
- 'null'
items:
type: string
piiAction:
type:
- string
- 'null'
eventType:
type:
- string
- 'null'
severity:
type:
- string
- 'null'
enum:
- critical
- high
- medium
- low
- info
- null
details:
type:
- object
- 'null'
userId:
type:
- string
- 'null'
actorKind:
type:
- string
- 'null'
actorId:
type:
- string
- 'null'
actorName:
type:
- string
- 'null'
traceId:
type:
- string
- 'null'
requestMetadata:
type:
- object
- 'null'
connectionSlug:
type:
- string
- 'null'
restoredFromArchiveId:
type:
- string
- 'null'
createdAt:
type: string
format: date-time
CursorListMeta:
allOf:
- $ref: '#/components/schemas/ListMeta'
- type: object
properties:
nextCursor:
type:
- string
- 'null'
description: >-
Set when the page is full. Pass it back as `cursor` for the next
page. `null` means there is nothing more to fetch.
ListMeta:
type: object
required:
- total
- limit
- offset
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
Error:
type: object
required:
- error
properties:
error:
type: string
ForbiddenError:
type: object
properties:
error:
type: string
example: Forbidden
required:
type: string
description: The permission the caller lacks.
example: policies:write
responses:
Unauthorized:
description: No valid session or API key, or the key's creator is no longer a member.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
Forbidden:
description: The caller lacks the required permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: ig_...
description: >-
An Igris API key. It acts with the current role and permission overrides
of the member who created it.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.