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

# Export Audit Events

> The Organization's audit trail, oldest first: what its people, keys and
the system did there -- role changes, key rotations, policy edits, sign-ins.

Every entry but each scan's own decision, which is an event on
`/api/v1/interactions`. Requires a Plan that includes the audit trail.

Guide: [SIEM export](https://docs.promptguard.co/integrations/siem-export#audit-events)



## OpenAPI

````yaml /api-reference/openapi-developer.json get /api/v1/audit-events
openapi: 3.1.0
info:
  title: PromptGuard Developer API
  description: >-
    Public API for developers to integrate PromptGuard security into their
    applications
  version: 1.0.0
servers:
  - url: https://api.promptguard.co
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/audit-events:
    get:
      tags:
        - SIEM export
      summary: Export Audit Events
      description: >-
        The Organization's audit trail, oldest first: what its people, keys and

        the system did there -- role changes, key rotations, policy edits,
        sign-ins.


        Every entry but each scan's own decision, which is an event on

        `/api/v1/interactions`. Requires a Plan that includes the audit trail.


        Guide: [SIEM
        export](https://docs.promptguard.co/integrations/siem-export#audit-events)
      operationId: export_audit_events_api_v1_audit_events_get
      parameters:
        - name: since
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: 'Read events from this time (ISO 8601). Default: 24 hours ago.'
            title: Since
          description: 'Read events from this time (ISO 8601). Default: 24 hours ago.'
        - name: until
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: Read events before this time.
            title: Until
          description: Read events before this time.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: '`next_cursor` from the previous page; replaces `since`.'
            title: Cursor
          description: '`next_cursor` from the previous page; replaces `since`.'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: Events per page.
            default: 100
            title: Limit
          description: Events per page.
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditExportPage'
              example:
                organization_id: 12613a5a-ff26-4e72-8105-a36b40327a7c
                organization_name: Acme Corp
                events:
                  - schema_version: '1'
                    event: audit_event
                    event_id: audit_1730453400123_9f2c41d07a6e
                    timestamp: '2026-11-01T09:30:00.123000+00:00'
                    organization_id: 12613a5a-ff26-4e72-8105-a36b40327a7c
                    organization_name: Acme Corp
                    project_id: null
                    project: null
                    actor_type: user
                    actor_id: 9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f
                    actor_ip: 203.0.113.7
                    category: configuration
                    action: member_role_changed
                    severity: warning
                    outcome: success
                    resource_type: membership
                    resource_id: 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9
                    description: Changed a member's role from member to admin
                    details:
                      old_role: member
                      new_role: admin
                    integrity_hash: >-
                      3b1f9a0c6d2e4f8a7b5c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a
                    text: >-
                      [PromptGuard] Audit: member role changed in *Acme Corp*
                      (success)
                    dashboard_url: >-
                      https://app.promptguard.co/dashboard/audit-log?org=12613a5a-ff26-4e72-8105-a36b40327a7c
                  - schema_version: '1'
                    event: audit_event
                    event_id: audit_1730453455871_04be7c9132fa
                    timestamp: '2026-11-01T09:30:55.871000+00:00'
                    organization_id: 12613a5a-ff26-4e72-8105-a36b40327a7c
                    organization_name: Acme Corp
                    project_id: null
                    project: null
                    actor_type: user
                    actor_id: 9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f
                    actor_ip: 203.0.113.7
                    category: security
                    action: api_key_rotated
                    severity: info
                    outcome: success
                    resource_type: api_key
                    resource_id: 473ae10c-5be1-467a-8c3a-341dec5a7e88
                    description: Rotated API key Production API
                    details: {}
                    integrity_hash: >-
                      8e2d4c6b0a9f7e5d3c1b2a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d
                    text: >-
                      [PromptGuard] Audit: api key rotated in *Acme Corp*
                      (success)
                    dashboard_url: >-
                      https://app.promptguard.co/dashboard/audit-log?org=12613a5a-ff26-4e72-8105-a36b40327a7c
                next_cursor: YXVkaXR8MTg0Mg
                has_more: false
        '401':
          description: Missing, malformed, unknown, disabled or expired API key
          content:
            application/json:
              examples:
                missing_api_key:
                  summary: No X-API-Key header
                  value:
                    error:
                      message: >-
                        PromptGuard API key required. Please provide via
                        X-API-Key header.
                      type: authentication_error
                      code: missing_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#missing_api_key
                malformed_api_key:
                  summary: Not a pg_live_ key
                  value:
                    error:
                      message: Invalid API key format
                      type: authentication_error
                      code: invalid_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#invalid_api_key
                unknown_api_key:
                  summary: No such key
                  value:
                    error:
                      message: Invalid API key
                      type: authentication_error
                      code: invalid_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#invalid_api_key
                disabled_api_key:
                  summary: Key disabled
                  value:
                    error:
                      message: API key is disabled
                      type: authentication_error
                      code: disabled_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#disabled_api_key
                expired_api_key:
                  summary: Key expired
                  value:
                    error:
                      message: API key has expired
                      type: authentication_error
                      code: expired_api_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#expired_api_key
              schema:
                $ref: '#/components/schemas/AuthErrorEnvelope'
        '403':
          description: Refused by the key's scopes or the organization's IP allowlist
          content:
            application/json:
              examples:
                scope_denied:
                  summary: The key's scopes exclude this endpoint
                  value:
                    error:
                      message: >-
                        This API key's scopes do not permit this endpoint.
                        Create a key with the required scope or use an
                        unrestricted key.
                      type: insufficient_scope
                      code: scope_denied
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#scope_denied
                scan_only_credential:
                  summary: A scan-only device credential
                  value:
                    error:
                      message: This credential is scan-only; endpoint not permitted.
                      type: insufficient_scope
                      code: scope_denied
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#scope_denied
                read_only_key:
                  summary: A SIEM export key
                  value:
                    error:
                      message: >-
                        This is a read-only export key. It may only GET
                        /api/v1/alerts, /api/v1/audit-events,
                        /api/v1/audit-events/stream, /api/v1/interactions and
                        /api/v1/interactions/stream.
                      type: insufficient_scope
                      code: read_only_key
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#read_only_key
                ip_not_allowed:
                  summary: Caller IP outside the allowlist
                  value:
                    error:
                      message: Request IP is not in the organization's allowlist
                      type: permission_error
                      code: ip_not_allowed
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#ip_not_allowed
                ip_allowlist_error:
                  summary: Allowlist could not be checked
                  value:
                    error:
                      message: IP allowlist validation failed
                      type: permission_error
                      code: ip_allowlist_error
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#ip_allowlist_error
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Per-minute rate limit reached; retry after `retry_after` seconds
          content:
            application/json:
              examples:
                rate_limit_exceeded:
                  summary: Per-minute limit reached
                  value:
                    error:
                      message: >-
                        Rate limit exceeded: your plan allows 60 requests per
                        minute. Please retry later.
                      type: rate_limit_exceeded
                      code: rate_limit_exceeded
                      retry_after: 42
                      doc_url: >-
                        https://docs.promptguard.co/production/error-handling#rate_limit_exceeded
              schema:
                $ref: '#/components/schemas/RateLimitErrorEnvelope'
      externalDocs:
        description: 'Guide: SIEM export'
        url: https://docs.promptguard.co/integrations/siem-export#audit-events
components:
  schemas:
    AuditExportPage:
      properties:
        organization_id:
          type: string
          title: Organization Id
        organization_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Name
        events:
          items:
            $ref: '#/components/schemas/AuditEventRecord'
          type: array
          title: Events
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Where this page ended. Pass it back as `cursor` to read on; it is
            returned even when the page is short, so a poller always has its
            place. Null only when there was no position to report.
        has_more:
          type: boolean
          title: Has More
          description: Whether another page is ready now.
      type: object
      required:
        - organization_id
        - organization_name
        - events
        - next_cursor
        - has_more
      title: AuditExportPage
      description: One page of an Organization's audit trail, oldest first.
    AuthErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          examples:
            - code: missing_api_key
              message: >-
                PromptGuard API key required. Please provide via X-API-Key
                header.
              type: authentication_error
      type: object
      required:
        - error
      title: AuthErrorEnvelope
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorEnvelope
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      example:
        detail:
          - type: missing
            loc:
              - body
              - messages
            msg: Field required
            input:
              direction: input
    RateLimitErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/RateLimitErrorDetail'
      type: object
      required:
        - error
      title: RateLimitErrorEnvelope
    AuditEventRecord:
      properties:
        schema_version:
          type: string
          title: Schema Version
        event:
          type: string
          title: Event
          description: '`audit_event`.'
        event_id:
          type: string
          title: Event Id
        timestamp:
          type: string
          title: Timestamp
          description: When it happened, ISO 8601 with offset.
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
        organization_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Name
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
          description: Null for an action on the whole organization.
        project:
          anyOf:
            - type: string
            - type: 'null'
          title: Project
          description: The project's name.
        category:
          type: string
          title: Category
          description: >-
            `authentication`, `authorization`, `data_access`,
            `data_modification`, `configuration`, `security`, `system` or
            `compliance`.
        action:
          type: string
          title: Action
          description: What was done, such as `member_role_changed`.
        severity:
          type: string
          title: Severity
          description: '`debug`, `info`, `warning`, `error` or `critical`.'
        outcome:
          type: string
          title: Outcome
          description: '`success`, `failure`, `denied` or `error`.'
        actor_type:
          type: string
          title: Actor Type
          description: '`user`, `api_key`, `service` or `system`.'
        actor_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Actor Id
          description: 'Who did it: a user id, or null for the system.'
        actor_ip:
          anyOf:
            - type: string
            - type: 'null'
          title: Actor Ip
        resource_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Resource Type
        resource_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Resource Id
        description:
          type: string
          title: Description
        details:
          additionalProperties: true
          type: object
          title: Details
        integrity_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Integrity Hash
          description: The entry's seal on its organization's tamper-evident chain.
        dashboard_url:
          type: string
          title: Dashboard Url
          description: Opens the audit log in its Organization.
        text:
          type: string
          title: Text
      type: object
      required:
        - schema_version
        - event
        - event_id
        - timestamp
        - organization_id
        - organization_name
        - project_id
        - project
        - category
        - action
        - severity
        - outcome
        - actor_type
        - actor_id
        - actor_ip
        - resource_type
        - resource_id
        - description
        - details
        - integrity_hash
        - dashboard_url
        - text
      title: AuditEventRecord
      description: |-
        One entry of an Organization's audit trail, in the SIEM event contract
        (schema_version 1): what a person, a key or the system did there.
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error description
        type:
          type: string
          title: Type
          description: Error category, e.g. 'authentication_error'
        code:
          type: string
          title: Code
          description: Machine-readable error code
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
          description: >-
            The error catalogue's entry for `code` (cause and fix); present when
            the catalogue documents the code
      type: object
      required:
        - message
        - type
        - code
      title: ErrorDetail
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    RateLimitErrorDetail:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
          description: '''rate_limit_exceeded'''
        code:
          type: string
          title: Code
          description: '''rate_limit_exceeded'''
        retry_after:
          type: integer
          title: Retry After
          description: Seconds until the window resets; also `Retry-After`
        doc_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Url
          description: >-
            The error catalogue's entry for `code` (cause and fix); present when
            the catalogue documents the code
      type: object
      required:
        - message
        - type
        - code
        - retry_after
      title: RateLimitErrorDetail
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        PromptGuard API key for developer endpoints. Keys start with pg_live_
        and are created in the dashboard.

````

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