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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# List workspace audit events

> List security-sensitive control-plane changes for the authenticated workspace.

> [!NOTE]
>
> This endpoint requires the `activity:read` management capability. OAuth callers must also have the workspace owner or admin role.

Events contain sanitized metadata only. Plaintext credentials, credential hashes, authorization headers, full scope lists, and request bodies are never returned.


## OpenAPI

````yaml openapi/v1/openapi.yaml GET /audit-events
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Global routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /audit-events:
    get:
      tags:
        - Gateway
      summary: List workspace audit events
      description: >-
        Returns security-sensitive control-plane changes for the authenticated
        workspace. Requires an owner or admin identity and the activity:read
        management capability.
      operationId: listWorkspaceAuditEvents
      parameters:
        - name: limit
          in: query
          description: Maximum number of audit events to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          description: Opaque cursor returned by the previous page.
          schema:
            type: string
        - name: action
          in: query
          description: Filter by an exact audit action.
          schema:
            type: string
        - name: target_type
          in: query
          description: Filter by an exact audit target type.
          schema:
            type: string
      responses:
        '200':
          description: Workspace audit events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceAuditEventListResponse'
        '400':
          description: Invalid cursor or query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing activity scope or administrative role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WorkspaceAuditEventListResponse:
      type: object
      required:
        - data
        - has_more
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceAuditEvent'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          description: >-
            The error object (`code`, `message`, `type`, `param` and optional
            `metadata`) that OpenAI-compatible SDKs read. Earlier responses
            returned the code string here; it is now also returned as top-level
            `code`.
          oneOf:
            - type: string
            - $ref: '#/components/schemas/ErrorObject'
          example:
            code: validation_error
            message: 'Unknown parameter: foo'
            type: invalid_request_error
            param: foo
        code:
          type: string
          description: The error code, the same value as `error.code`.
          example: validation_error
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    WorkspaceAuditEvent:
      type: object
      required:
        - id
        - workspace_id
        - action
        - target_type
        - target_id
        - metadata
        - created_at
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        actor_user_id:
          type: string
          format: uuid
          nullable: true
        actor:
          allOf:
            - $ref: '#/components/schemas/WorkspaceAuditEventActor'
          nullable: true
        action:
          type: string
          example: api_key.rotated
        target_type:
          type: string
          example: api_key
        target_id:
          type: string
        target_name:
          type: string
          nullable: true
        metadata:
          $ref: '#/components/schemas/WorkspaceAuditEventMetadata'
        request_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
      additionalProperties: false
    ErrorObject:
      type: object
      description: >-
        A gateway error in the shape OpenAI's SDKs read. `type` is set from the
        HTTP status: invalid_request_error for most 4xx, authentication_error
        (401), insufficient_quota (402), permission_error (403), not_found_error
        (404), rate_limit_error (429), service_unavailable (503), overloaded
        (529) and server_error for other 5xx.
      required:
        - code
        - message
        - type
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable explanation of the failure.
          example: 'Unknown parameter: foo'
        type:
          type: string
          description: The error type, following OpenAI's documented error types.
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - insufficient_quota
            - server_error
            - service_unavailable
            - overloaded
          example: invalid_request_error
        param:
          type: string
          nullable: true
          description: The request parameter that caused the error, when known.
          example: foo
        metadata:
          type: object
          description: >-
            Structured detail also returned at the top level, such as the
            failing provider, `reason`, `failed_statuses`, `retry_after_seconds`
            or `upstream_error`.
          additionalProperties: true
      additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    WorkspaceAuditEventActor:
      type: object
      properties:
        display_name:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
      additionalProperties: false
    WorkspaceAuditEventMetadata:
      type: object
      properties:
        prefix:
          type: string
          nullable: true
        status:
          type: string
        changedFields:
          type: array
          items:
            type: string
        limits:
          $ref: '#/components/schemas/WorkspaceAuditEventLimits'
        replacementKeyId:
          type: string
        replacementKeyName:
          type: string
        previousKeyExpiresAt:
          type: string
          format: date-time
          nullable: true
        accessTemplate:
          type: string
        expiresAt:
          type: string
          format: date-time
          nullable: true
      additionalProperties: true
    WorkspaceAuditEventLimits:
      type: object
      properties:
        dailyRequests:
          type: integer
          minimum: 0
        weeklyRequests:
          type: integer
          minimum: 0
        monthlyRequests:
          type: integer
          minimum: 0
        dailyCostNanos:
          type: integer
          minimum: 0
        weeklyCostNanos:
          type: integer
          minimum: 0
        monthlyCostNanos:
          type: integer
          minimum: 0
        softBlocked:
          type: boolean
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````

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