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

# List model billing events

> Returns successful billable outputs with the exact price and discount frozen when each output completed.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/models/billing-events
openapi: 3.1.0
info:
  description: >-
    Deterministic biological evidence primitives with typed resource, list, and
    error responses. Each operation documents its own response shape,
    provenance, warnings, and transport headers.
  title: Rafflesia API
  version: 0.1.0
servers:
  - description: Production
    url: https://api.rafflesia.ai
security:
  - bearerAuth: []
paths:
  /v1/models/billing-events:
    get:
      tags:
        - Models
      summary: List model billing events
      description: >-
        Returns successful billable outputs with the exact price and discount
        frozen when each output completed.
      operationId: models.billing_events
      parameters:
        - description: >-
            Maximum number of items to return. The actual maximum depends on
            query type and expansions.
          example: 50
          explode: false
          in: query
          name: limit
          schema:
            description: >-
              Maximum number of items to return. The actual maximum depends on
              query type and expansions.
            examples:
              - 50
            format: int64
            minimum: 1
            type: integer
        - description: >-
            Pagination cursor from the previous response. Encodes the page
            number.
          example: Mg==
          explode: false
          in: query
          name: cursor
          schema:
            description: >-
              Pagination cursor from the previous response. Encodes the page
              number.
            examples:
              - Mg==
            type: string
        - description: >-
            Start date in ISO8601 format (for example, '2025-01-01T00:00:00Z' or
            '2025-01-01'). Defaults to 24 hours ago.
          example: '2025-01-01T00:00:00Z'
          explode: false
          in: query
          name: start
          schema:
            anyOf:
              - format: date-time
                type: string
              - pattern: ^\d{4}-\d{2}-\d{2}$
                type: string
            description: >-
              Start date in ISO8601 format (for example, '2025-01-01T00:00:00Z'
              or '2025-01-01'). Defaults to 24 hours ago.
            examples:
              - '2025-01-01T00:00:00Z'
        - description: >-
            Exclusive end date in ISO8601 format (for example,
            '2025-02-01T00:00:00Z' or '2025-02-01'). Defaults to the current
            time.
          example: '2025-02-01T00:00:00Z'
          explode: false
          in: query
          name: end
          schema:
            anyOf:
              - format: date-time
                type: string
              - pattern: ^\d{4}-\d{2}-\d{2}$
                type: string
            description: >-
              Exclusive end date in ISO8601 format (for example,
              '2025-02-01T00:00:00Z' or '2025-02-01'). Defaults to the current
              time.
            examples:
              - '2025-02-01T00:00:00Z'
        - description: >-
            Filter by 1-50 endpoint IDs. Accepts repeated or comma-separated
            values.
          example:
            - rafflesia/homology
          explode: true
          in: query
          name: endpoint_id
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
            description: >-
              Filter by 1-50 endpoint IDs. Accepts repeated or comma-separated
              values.
            examples:
              - - rafflesia/homology
          style: form
        - description: >-
            Filter by 1-50 request IDs. Accepts repeated or comma-separated
            values.
          example:
            - run_0123456789abcdef01234567
          explode: true
          in: query
          name: request_id
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
            description: >-
              Filter by 1-50 request IDs. Accepts repeated or comma-separated
              values.
            examples:
              - - run_0123456789abcdef01234567
          style: form
        - description: >-
            Filter by 1-50 API key IDs. Accepts repeated or comma-separated
            values.
          example:
            - key_abc123
          explode: true
          in: query
          name: api_key_id
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
            description: >-
              Filter by 1-50 API key IDs. Accepts repeated or comma-separated
              values.
            examples:
              - - key_abc123
          style: form
        - description: >-
            Filter by 1-50 team-member login usernames. Accepts repeated or
            comma-separated values.
          example:
            - alice
          explode: true
          in: query
          name: login_username
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
            description: >-
              Filter by 1-50 team-member login usernames. Accepts repeated or
              comma-separated values.
            examples:
              - - alice
          style: form
        - description: >-
            Use auth_method for a formatted label and auth_method_structured for
            a machine-readable identity.
          example:
            - auth_method
          explode: true
          in: query
          name: expand
          schema:
            anyOf:
              - type: string
              - items:
                  type: string
                type: array
            description: >-
              Use auth_method for a formatted label and auth_method_structured
              for a machine-readable identity.
            examples:
              - - auth_method
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelBillingEventList'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Bad Request
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Unauthorized
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Payment Required
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Forbidden
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Not Found
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Method Not Allowed
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Not Acceptable
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Request Timeout
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Gone
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Unprocessable Entity
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Too Many Requests
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            RateLimit:
              description: Remaining capacity and reset interval for this refusal.
              schema:
                type: string
            RateLimit-Policy:
              description: Effective request, queue, or execution-capacity policy.
              schema:
                type: string
            Retry-After:
              description: Whole seconds to wait before retrying a transient error.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '499':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Client Closed Request
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Internal Server Error
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Bad Gateway
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            Retry-After:
              description: Whole seconds to wait before retrying a transient error.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Service Unavailable
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            Retry-After:
              description: Whole seconds to wait before retrying a transient error.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionEnvelopeExecutionErrorData'
          description: Gateway Timeout
          headers:
            Rafflesia-Contract-Digest:
              description: Digest of the full API contract used for this response.
              schema:
                type: string
            Rafflesia-Error-Type:
              description: Stable machine-readable error code, identical to error.code.
              schema:
                type: string
            Rafflesia-Request-Timeout-Type:
              description: >-
                Set to user when the caller-supplied start deadline caused this
                response.
              schema:
                enum:
                  - user
                type: string
            Rafflesia-Retryable:
              description: Whether retrying the identical pinned request may succeed.
              schema:
                enum:
                  - 'true'
                  - 'false'
                type: string
            Rafflesia-Version:
              description: API contract version used for this response.
              schema:
                type: string
            Retry-After:
              description: Whole seconds to wait before retrying a transient error.
              schema:
                type: string
            X-Rafflesia-Billable-Units:
              description: >-
                Frozen units billed when execution produced a chargeable
                terminal result.
              schema:
                type: string
            X-Rafflesia-Runner-Hints:
              description: Best-effort affinity hint suitable for a later related request.
              schema:
                type: string
            X-Rafflesia-Served-From:
              description: Execution worker identifier that handled the latest attempt.
              schema:
                type: string
            X-Request-ID:
              description: Request identifier for support and log correlation.
              schema:
                type: string
      x-codeSamples:
        - lang: bash
          source: |
            curl --request GET \
              --url "https://api.rafflesia.ai/v1/models/billing-events" \
              --header "Authorization: Bearer $RAFFLESIA_API_KEY"
components:
  schemas:
    ModelBillingEventList:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/ModelBillingEventList.json
          format: uri
          readOnly: true
          type: string
        billing_events:
          description: Individual billing event records.
          items:
            $ref: '#/components/schemas/ModelBillingEvent'
          type: array
        has_more:
          description: Whether more results are available; derived from next_cursor.
          type: boolean
        next_cursor:
          description: >-
            Cursor for the next page of results, or null when there are no more
            pages.
          type:
            - string
            - 'null'
      required:
        - next_cursor
        - has_more
        - billing_events
      type: object
    ExecutionEnvelopeExecutionErrorData:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - >-
              https://example.com/schemas/ExecutionEnvelopeExecutionErrorData.json
          format: uri
          readOnly: true
          type: string
        data:
          $ref: '#/components/schemas/ExecutionErrorData'
          description: Operation result data. Absent when the operation did not succeed.
        error:
          $ref: '#/components/schemas/ExecutionAPIError'
          description: Structured execution error information.
        evidence:
          $ref: '#/components/schemas/EvidenceSummary'
          description: Mechanical evidence summary for agent inspection and chaining.
        ok:
          description: Whether the operation succeeded.
          type: boolean
        provenance:
          $ref: '#/components/schemas/Provenance'
          description: Execution provenance.
        warnings:
          description: Non-fatal warnings.
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - ok
        - warnings
        - provenance
      type: object
    ModelBillingEvent:
      additionalProperties: false
      properties:
        auth_method:
          description: >-
            Authentication method label. Only populated when 'auth_method' is
            included in expand.
          type: string
        auth_method_structured:
          $ref: '#/components/schemas/ModelAuthMethod'
          description: >-
            Structured authentication method identity. Only populated when
            'auth_method_structured' is included in expand.
        cost_discount:
          description: >-
            Discount applied to this request in USD (cost_subtotal −
            cost_total).
          format: double
          minimum: 0
          type: number
        cost_estimate_nano_usd:
          description: >-
            Amount charged after discounts in whole nano USD; the same charge as
            cost_total (1 USD = 1,000,000,000 nano USD).
          format: int64
          minimum: 0
          type: integer
        cost_subtotal:
          description: Cost before discounts in USD (output_units × unit_price).
          format: double
          minimum: 0
          type: number
        cost_total:
          description: >-
            Amount charged after discounts in USD (cost_subtotal −
            cost_discount).
          format: double
          minimum: 0
          type: number
        endpoint_id:
          description: Endpoint identifier that was used.
          type: string
        output_units:
          description: Custom billing units for this request.
          format: double
          minimum: 0
          type:
            - number
            - 'null'
        percent_discount:
          description: >-
            Discount percentage applied to this request (for example, 10 = 10%
            discount).
          format: double
          maximum: 100
          minimum: 0
          type:
            - number
            - 'null'
        request_id:
          description: Unique identifier for the request.
          type: string
        timestamp:
          description: Request timestamp in ISO8601 format.
          format: date-time
          type: string
        unit_price:
          description: Unit price for this request.
          format: double
          minimum: 0
          type:
            - number
            - 'null'
      required:
        - request_id
        - endpoint_id
        - timestamp
        - output_units
        - unit_price
        - percent_discount
        - cost_subtotal
        - cost_discount
        - cost_total
        - cost_estimate_nano_usd
      type: object
    ExecutionErrorData:
      additionalProperties: false
      type: object
    ExecutionAPIError:
      additionalProperties: false
      properties:
        code:
          description: Stable specific error code. Branch on this value instead of message.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured error details retained for compatibility.
          type: object
        doc_url:
          description: Stable documentation URL for this error code.
          type: string
        errors:
          description: >-
            One or more exact validation or execution failures. Machine logic
            should use type, loc, and ctx; msg is for people.
          items:
            $ref: '#/components/schemas/APIErrorDetail'
          type: array
        is_retryable:
          description: >-
            Whether retrying the identical pinned request may succeed without
            changing its input.
          type: boolean
        message:
          description: Human-readable actionable explanation. Do not parse this value.
          type: string
        param:
          description: Request field responsible for the error when known.
          type: string
        request_id:
          description: Request identifier to provide when reporting this occurrence.
          type: string
        type:
          description: Stable coarse error category.
          enum:
            - invalid_request_error
            - resource_missing
            - resource_expired
            - conflict_error
            - rate_limit_error
            - authentication_error
            - permission_error
            - billing_error
            - api_error
          type: string
      required:
        - type
        - code
        - message
        - doc_url
        - is_retryable
      type: object
    EvidenceSummary:
      additionalProperties: false
      properties:
        duration_ms:
          description: >-
            Primary elapsed duration in milliseconds when the response exposes
            one.
          format: int64
          type: integer
        input_refs:
          description: >-
            Input references detected from request fields such as object_id,
            structure_id, target_id, and sequence_id.
          items:
            type: string
          type:
            - array
            - 'null'
        object_refs:
          description: Object ids or object refs visible in the response/provenance.
          items:
            type: string
          type:
            - array
            - 'null'
        output_refs:
          description: Output references detected from response data and generated objects.
          items:
            type: string
          type:
            - array
            - 'null'
        row_count:
          description: >-
            Primary row count or returned row count when the response exposes
            one.
          format: int64
          type: integer
        warnings_count:
          description: Number of non-fatal warnings in the envelope.
          format: int64
          type: integer
      required:
        - warnings_count
      type: object
    Provenance:
      additionalProperties: false
      properties:
        cache_hit:
          description: Whether cached output was reused.
          type: boolean
        created_at:
          description: UTC timestamp.
          type: string
        database_snapshots:
          description: Database snapshots used.
          items:
            $ref: '#/components/schemas/DatabaseSnapshot'
          type:
            - array
            - 'null'
        generated_object_ids:
          description: Object ids created by the operation.
          items:
            type: string
          type:
            - array
            - 'null'
        input_hash:
          description: SHA-256 hash of canonical request input.
          type: string
        operation:
          description: Primitive operation id.
          type: string
        parameters_hash:
          description: SHA-256 hash of parameters.
          type: string
        request_id:
          description: Unique request identifier.
          type: string
        server_version:
          description: Server version.
          type: string
        tool_versions:
          description: Tool versions used.
          items:
            $ref: '#/components/schemas/ToolVersion'
          type:
            - array
            - 'null'
      required:
        - request_id
        - operation
        - created_at
        - server_version
      type: object
    Warning:
      additionalProperties: false
      properties:
        code:
          description: Stable warning code.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured warning details.
          type: object
        message:
          description: Human-readable warning message.
          type: string
      required:
        - code
        - message
      type: object
    ModelAuthMethod:
      additionalProperties: false
      properties:
        api_key_id:
          description: API key ID, present when the request was made with an API key.
          type: string
        detail:
          description: >-
            Human-readable summary of the authentication method (key alias,
            login username, or 'User token'/'None').
          type: string
        login_username:
          description: >-
            Team member login username (nickname), present when the request was
            made with a user login token resolvable to a team member.
          type: string
      required:
        - detail
      type: object
    APIErrorDetail:
      additionalProperties: false
      properties:
        ctx:
          additionalProperties: {}
          description: Structured constraint or failure context.
          type: object
        input:
          description: Offending non-sensitive scalar when it is safe and useful to echo.
        loc:
          description: >-
            Path to the failing value, beginning with body, query, path, or
            header.
          items:
            type: string
          type: array
        msg:
          description: Human-readable explanation. Do not parse this value.
          type: string
        type:
          description: Stable machine-readable failure type.
          type: string
        url:
          description: Documentation URL for this failure type.
          type: string
      required:
        - loc
        - msg
        - type
        - url
      type: object
    DatabaseSnapshot:
      additionalProperties: false
      properties:
        digest:
          type: string
        kind:
          type: string
        name:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
    ToolVersion:
      additionalProperties: false
      properties:
        name:
          type: string
        path:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
  securitySchemes:
    bearerAuth:
      description: 'A Rafflesia API key, sent as `Authorization: Bearer <key>`.'
      scheme: bearer
      type: http

````