> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit API

> Query and export audit logs via the OpenIndex API.

OpenIndex writes audit records for significant system events — work item mutations, agent runs, domain changes, calendar syncs, and more. Use the audit API to query, filter, and export these records.

All audit endpoints require a Bearer token. See [API Authentication](/api/authentication).

## What the audit log captures

<AccordionGroup>
  <Accordion title="Work item events">
    * Work item creation, updates, and deletion
    * Status transitions (including agent claim and complete)
    * Stage gate progressions
    * Comment and attachment changes
    * Custom field value changes
  </Accordion>

  <Accordion title="Agent runs">
    * Agent claim and completion events
    * Agent dispatch and execution outcomes
    * Stage gate advancement by agents
  </Accordion>

  <Accordion title="Domain and membership changes">
    * Domain creation, updates, and deletion
    * Member additions, role changes, and removals
  </Accordion>

  <Accordion title="Calendar sync">
    * Calendar source creation and deletion
    * Sync success and failure events for each source
  </Accordion>

  <Accordion title="Admin actions">
    * User suspension and unsuspension
    * AI provider configuration changes
    * Email infrastructure provisioning
  </Accordion>
</AccordionGroup>

## List audit log entries

```bash theme={null}
GET /audit
Authorization: Bearer <your-pat>
```

Returns audit log entries in reverse chronological order.

<ParamField path="query.workItemKey" type="string">
  Filter entries for a specific work item (e.g. `OPS-42`).
</ParamField>

<ParamField path="query.domainId" type="string">
  Filter entries for a specific domain.
</ParamField>

<ParamField path="query.eventType" type="string">
  Filter by event type (e.g. `work_item.status_changed`, `agent.claimed`).
</ParamField>

<ParamField path="query.userId" type="string">
  Filter entries by the user who performed the action.
</ParamField>

<ParamField path="query.before" type="string">
  Return entries before this ISO 8601 timestamp.
</ParamField>

<ParamField path="query.after" type="string">
  Return entries after this ISO 8601 timestamp.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://your-deployment.convex.site/audit?workItemKey=OPS-42' \
    --header 'Authorization: Bearer oi_pat_...'
  ```

  ```json Response theme={null}
  {
    "entries": [
      {
        "id": "audit_abc123",
        "eventType": "work_item.status_changed",
        "workItemKey": "OPS-42",
        "userId": "user_xyz789",
        "before": { "status": "in_progress" },
        "after": { "status": "completed" },
        "timestamp": "2026-03-31T10:05:00Z"
      }
    ],
    "cursor": "cursor_next_page"
  }
  ```
</CodeGroup>

## Export audit log

```bash theme={null}
GET /audit/export
Authorization: Bearer <your-pat>
```

Exports audit log entries as a downloadable file. Supports the same filter parameters as `GET /audit`.

<ParamField path="query.format" type="string" default="json">
  Export format: `json` or `csv`.
</ParamField>

<CodeGroup>
  ```bash JSON export theme={null}
  curl --request GET \
    --url 'https://your-deployment.convex.site/audit/export?format=json' \
    --header 'Authorization: Bearer oi_pat_...' \
    --output audit-export.json
  ```

  ```bash CSV export theme={null}
  curl --request GET \
    --url 'https://your-deployment.convex.site/audit/export?format=csv' \
    --header 'Authorization: Bearer oi_pat_...' \
    --output audit-export.csv
  ```
</CodeGroup>

**Via CLI:**

```bash theme={null}
# List audit entries for a work item
oi work-item audit list OPS-42

# Export audit log to CSV
oi work-item audit export OPS-42 --format csv --output ./export.csv
```

## Operational statistics

```bash theme={null}
GET /stats
Authorization: Bearer <your-pat>
```

Returns current operational statistics for the instance, including:

* Total work item counts by kind and status
* Active workflow counts
* Agent queue depth
* Recent sync activity

<ResponseField name="workItems" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="number">
      Total work items across all domains.
    </ResponseField>

    <ResponseField name="byKind" type="object">
      Counts broken down by `project`, `task`, and `sub_task`.
    </ResponseField>

    <ResponseField name="byStatus" type="object">
      Counts broken down by status value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="agentQueue" type="object">
  <Expandable title="properties">
    <ResponseField name="depth" type="number">
      Number of work items currently waiting for agent pickup.
    </ResponseField>

    <ResponseField name="claimed" type="number">
      Number of work items currently claimed by agents.
    </ResponseField>
  </Expandable>
</ResponseField>