# Audit log

The organization's audit log.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List audit events [#list-audit-events]

    <ApiEndpointHeader method="GET" path="/v1/audit_events" scope="audit:read" />

    Newest first, within your plan's audit retention. Pages forward with `starting_after`.
    Reading the audit log through the API is itself recorded in the audit log.
    On an AI team that turned on Protected files, a key that lacks `files:protected.read` (or whose person lacks it) gets `protected` in place of every AI Employee or skill name in that team's events: an AI Employee key in `details`, and on an event that names a file under `.claude/agents` or `.claude/skills`, every path in it (`resource_id` and the paths in `details`). An event with no team is treated this way when any team hides its AI Employees from the key.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return events older than this audit event id.
      </ApiParam>

      <ApiParam name="action" type="string">
        Only events with this action, for example `api_key.created`.
      </ApiParam>

      <ApiParam name="actor" type="string">
        Only events by this email address.
      </ApiParam>

      <ApiParam name="created[gte]" type="string (date-time)">
        Only events at or after this time.
      </ApiParam>

      <ApiParam name="created[lte]" type="string (date-time)">
        Only events at or before this time.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [AuditEvent](#auditevent) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of audit events.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/audit_events \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/audit_events', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/audit_events",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "audit_event",
          "id": "aud_eyJ0cyI6IjIwMjYtMTAtMTRUMTY6MDI6MTEuMzE4WiIsImlkIjoiOGM0ZjJhMTktNWQzZS00YjdhLTlmNjEtMmUwYzdkNWEzYjg0In0",
          "action": "api_key.created",
          "actor": {
            "email": "maya.chen@example.com",
            "name": "Maya Chen"
          },
          "resource_type": "api_key",
          "resource_id": "key_ff7QejQ24AGmu5tv2IXIdw",
          "team": null,
          "details": {
            "name": "CI deploy bot",
            "scopes": ["teams:read", "sessions:read"]
          },
          "ip_address": "203.0.113.24",
          "created_at": "2026-10-14T16:02:11.318Z"
        }
      ],
      "has_more": false,
      "retention_days": 90
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### AuditEvent [#auditevent]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="action" type="string" />

      <ApiParam name="actor" type="object" />

      <ApiParam name="resource_type" type="string or null" />

      <ApiParam name="resource_id" type="string or null" />

      <ApiParam name="team" type="string or null" />

      <ApiParam name="details" type="object or null" />

      <ApiParam name="ip_address" type="string or null" />

      <ApiParam name="created_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The AuditEvent object"
    {
      "object": "audit_event",
      "id": "aud_eyJ0cyI6IjIwMjYtMTAtMTRUMTY6MDI6MTEuMzE4WiIsImlkIjoiOGM0ZjJhMTktNWQzZS00YjdhLTlmNjEtMmUwYzdkNWEzYjg0In0",
      "action": "api_key.created",
      "actor": {
        "email": "maya.chen@example.com",
        "name": "Maya Chen"
      },
      "resource_type": "api_key",
      "resource_id": "key_ff7QejQ24AGmu5tv2IXIdw",
      "team": null,
      "details": {
        "name": "CI deploy bot",
        "scopes": ["teams:read", "sessions:read"]
      },
      "ip_address": "203.0.113.24",
      "created_at": "2026-10-14T16:02:11.318Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
