# Read and export the audit log

Every administrative change is recorded with who made it, what it touched, and when.

The **audit log** records sensitive actions in your organization and keeps
each record for at least two years.

**You need:** an owner or admin role. The log is read through the
[REST API](/api-reference) with your signed-in session; there is no dashboard
view or CLI command, and API keys can't read it. From a script, send the
dashboard's session cookie:
`curl --cookie "intro_cp_session=<value from your signed-in browser>" …`.

## What is recorded

| Area | Actions |
| --- | --- |
| Sign-in | Login, logout, failed login, sessions, impersonation start and end |
| Credentials | API keys, applications and their secrets and identity providers, bindings' credentials and variables |
| People | Invites, joins, role changes, disabling, removal, identity links |
| Agents | Projects, recipes, runtimes, experiments, endpoints, connectors, connections, channels |
| Organization | Settings, features, integrations, data plane deployments, billing |

Impersonation is Introspection staff signing in as a member. Each action taken
during it records the staff member in `impersonator_id` and `impersonator_name`.

Not recorded: tool calls, approvals, and annotations. Find those in
[conversations](/observe/conversations) and [annotations](/improve/annotate).

## 1. List events

```text
GET https://api.introspection.dev/v1/audit?start_date=2026-10-01T00:00:00Z&end_date=2026-10-15T00:00:00Z
```

Filters: `actor_type`, `actor_id`, `action` (for example `api_key.created`),
`action_category`, `target_type`, `target_id`, `project_id`, `success`,
`start_date`, `end_date`. Pages hold 50 events by default (`limit`, at most 100); pass `cursor` for
the next page.

## 2. Count events

```text
GET /v1/audit/counts?start_date=…&end_date=…&period=day
```

`start_date` and `end_date` are required. `period` is `hour`, `day`, `week`,
or `month`. Each row has `period_start`, `action`, `event_count`, and
`unique_actors`.

## 3. Export as CSV

```text
POST /v1/audit/export
{"filters": {"start_date": "2026-07-01T00:00:00Z", "end_date": "2026-10-01T00:00:00Z"}}
```

Poll `GET /v1/audit/exports/{id}` with the returned `id` until `status` is
`completed`, then download `file_url` before `file_expires_at`. The response has
`id`, `status` (pending, processing, completed, failed), `event_count`,
`file_url`, `file_expires_at`, `error_message`.

## Assemble evidence for a model review

| Evidence | Where |
| --- | --- |
| Which version ran | `recipe_git_commit_sha` on each [conversation](/observe/conversations#see-what-one-release-did) |
| What the change was tested against | Eval compare output saved by [CI](/improve/eval-ci) |
| Live comparisons | `introspection experiments get <id> -o json` ([Experiments](/improve/experiments)) |
| Who changed configuration | The audit CSV above |

## Verify

The export reaches `status: completed` and its `event_count` matches the
number of rows in the CSV.

## Limits

| Not supported | Do this instead |
| --- | --- |
| Audit entries for tool calls or approvals | Record decisions in your own system; read tool calls from conversations. |
| Streaming to a SIEM | Export on a schedule with a [service-account application](/identity/credentials#create-a-service-account) an owner or admin creates with `--allowed-scope audit:read --allowed-scope audit:export`; contact us for SIEM delivery. |

Read and export the audit log

Every administrative change is recorded with who made it, what it touched, and when.

The audit log records sensitive actions in your organization and keeps each record for at least two years.

You need: an owner or admin role. The log is read through the REST API with your signed-in session; there is no dashboard view or CLI command, and API keys can’t read it. From a script, send the dashboard’s session cookie: curl --cookie "intro_cp_session=<value from your signed-in browser>" ….

What is recorded

Area	Actions
Sign-in	Login, logout, failed login, sessions, impersonation start and end
Credentials	API keys, applications and their secrets and identity providers, bindings’ credentials and variables
People	Invites, joins, role changes, disabling, removal, identity links
Agents	Projects, recipes, runtimes, experiments, endpoints, connectors, connections, channels
Organization	Settings, features, integrations, data plane deployments, billing

Impersonation is Introspection staff signing in as a member. Each action taken during it records the staff member in impersonator_id and impersonator_name.

Not recorded: tool calls, approvals, and annotations. Find those in conversations and annotations.

1. List events


GET https://api.introspection.dev/v1/audit?start_date=2026-10-01T00:00:00Z&end_date=2026-10-15T00:00:00Z

Filters: actor_type, actor_id, action (for example api_key.created), action_category, target_type, target_id, project_id, success, start_date, end_date. Pages hold 50 events by default (limit, at most 100); pass cursor for the next page.

2. Count events


GET /v1/audit/counts?start_date=…&end_date=…&period=day

start_date and end_date are required. period is hour, day, week, or month. Each row has period_start, action, event_count, and unique_actors.

3. Export as CSV


POST /v1/audit/export
{"filters": {"start_date": "2026-07-01T00:00:00Z", "end_date": "2026-10-01T00:00:00Z"}}

Poll GET /v1/audit/exports/{id} with the returned id until status is completed, then download file_url before file_expires_at. The response has id, status (pending, processing, completed, failed), event_count, file_url, file_expires_at, error_message.

Assemble evidence for a model review

Evidence	Where
Which version ran	`recipe_git_commit_sha` on each conversation
What the change was tested against	Eval compare output saved by CI
Live comparisons	`introspection experiments get <id> -o json` (Experiments)
Who changed configuration	The audit CSV above

Verify

The export reaches status: completed and its event_count matches the number of rows in the CSV.

Limits

Not supported	Do this instead
Audit entries for tool calls or approvals	Record decisions in your own system; read tool calls from conversations.
Streaming to a SIEM	Export on a schedule with a service-account application an owner or admin creates with `--allowed-scope audit:read --allowed-scope audit:export`; contact us for SIEM delivery.