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

# List audit events

> Your organization's API audit trail, newest first: one event per authenticated request (one per record when a request names two), with the key, route, record ids and status. Never request or response content. Events are kept for 90 days.

| Requirement | Detail |
| - | - |
| **Scope** | `audit:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **Safety**
>
> * **Writes data:** No
> * **Safe to retry:** Yes
> * **Contacts an outside system:** None. Reads your organization's API audit log in HealOS.
> * **Dry run:** Not needed (read-only).

Lists your organization's External API audit log, newest first: which API key called which route, on which record id, with what status. Rows hold ids and route templates only (`/patients/{patientId}`), never request bodies, query values or record contents. Every row belongs to the calling key's own organization.

Narrow the list with `key_id`, `resource_type` and `resource_id`, or a `since` / `until` window. For the next (older) page, pass the previous page's `meta.next_cursor` as `cursor`. Rows can take a few seconds to appear: HealOS writes them in batches.

From the CLI: `healos audit list`. Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /audit-events
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /audit-events:
    get:
      tags:
        - Account
      summary: List audit events
      description: >-
        Your organization's API audit trail, newest first: one event per
        authenticated request (one per record when a request names two), with
        the key, route, record ids and status. Never request or response
        content. Events are kept for 90 days.
      parameters:
        - schema:
            type: string
            format: uuid
            description: Only events from this API key (its id, from the API Keys page).
          required: false
          name: key_id
          in: query
        - schema:
            type: string
            pattern: ^[a-z_]{1,48}$
            description: >-
              Only events about this kind of record: patient, document,
              appointment, provider, note, session, eligibility_check,
              prior_auth_request or ehr_action.
            example: patient
          required: false
          name: resource_type
          in: query
        - schema:
            type: string
            pattern: ^[A-Za-z0-9_.:-]{1,64}$
            description: Only events about this record id. Combine with resource_type.
          required: false
          name: resource_id
          in: query
        - schema:
            type: string
            format: date-time
            description: Events at or after this time (ISO 8601).
            example: '2026-10-01T00:00:00Z'
          required: false
          name: since
          in: query
        - schema:
            type: string
            format: date-time
            description: Events before this time (ISO 8601).
          required: false
          name: until
          in: query
        - schema:
            type: string
            pattern: ^\d+$
            default: '50'
            description: Events per page, 1-200 (default 50).
            example: '50'
          required: false
          name: limit
          in: query
        - schema:
            type: string
            pattern: ^[1-9]\d{0,18}$
            description: >-
              `meta.next_cursor` from the previous page. Omit for the newest
              events.
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: A page of audit events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventListResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs audit:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    AuditEventListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
        meta:
          type: object
          properties:
            limit:
              type: number
            next_cursor:
              type: string
              nullable: true
              description: >-
                Pass as `cursor` for the next (older) page; null on the last
                page.
          required:
            - limit
            - next_cursor
      required:
        - data
        - meta
    ValidationError:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    AuditEvent:
      type: object
      properties:
        id:
          type: string
          description: Event id; events are returned newest first.
        created_at:
          type: string
        key_id:
          type: string
        user_id:
          type: string
          nullable: true
          description: The admin who owns the key.
        request_id:
          type: string
          nullable: true
          description: >-
            Shared by the events one request produced (one per resource it
            named).
        method:
          type: string
          example: GET
        route:
          type: string
          example: /patients/{patientId}
        resource_type:
          type: string
          nullable: true
          example: patient
        resource_id:
          type: string
          nullable: true
        status:
          type: integer
          example: 200
      required:
        - id
        - created_at
        - key_id
        - user_id
        - request_id
        - method
        - route
        - resource_type
        - resource_id
        - status
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.