Vertesia Costs API

openapi: 3.2.0
info:
  title: Vertesia Costs API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Costs
  description: Cost endpoints expose billing analytics, model pricing, and run-level metering for project and account usage.
paths:
  /cost/analytics:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: GetCostAnalytics
      tags:
      - Costs
      summary: Compute cost analytics
      description: 'Computes aggregated cost analytics for the current project or, in org scope, across the account.


        **Required permissions:** `billing:read`'
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Aggregated cost analytics by summary, dimension, and time series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostAnalyticsResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        '503':
          description: Cost analytics is not available on this deployment, or its model pricing is not synced yet.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - billing:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/cost.ts
        className: CostResource
        methodName: getAnalytics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostAnalyticsQuery'
  /cost/model-prices:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: GetModelPrices
      tags:
      - Costs
      summary: List model prices
      description: 'Lists model pricing for a selected time range, including list prices and the effective pricing window used for billing.


        **Required permissions:** `billing:read`'
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type:
          - string
          - number
          description: Start time (ISO string or epoch ms)
        description: Start time (ISO string or epoch ms)
      - name: to
        in: query
        required: false
        schema:
          type:
          - string
          - number
          description: End time (ISO string or epoch ms)
        description: End time (ISO string or epoch ms)
      responses:
        '200':
          description: Model pricing comparison for the selected period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelPriceComparisonResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        '503':
          description: Cost analytics is not available on this deployment, or its model pricing is not synced yet.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - billing:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/cost.ts
        className: CostResource
        methodName: getModelPrices
  /cost/run-price:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: GetRunPrice
      tags:
      - Costs
      summary: Price a run
      description: 'Computes the billed cost for a single interaction run or agent run from audit metering rows.


        **Required permissions:** `billing:read`'
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: Pricing summary and model breakdown for the selected run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostRunPriceResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        '503':
          description: Cost analytics is not available on this deployment, or its model pricing is not synced yet.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - billing:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/cost.ts
        className: CostResource
        methodName: getRunPrice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostRunPriceQuery'
  /cost/export:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ExportCostData
      tags:
      - Costs
      summary: Export cost data
      description: 'Exports raw billable audit events as CSV for the selected time range and scope.


        **Required permissions:** `billing:read`'
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type:
          - string
          - number
          description: Start time (ISO string or epoch ms)
        description: Start time (ISO string or epoch ms)
      - name: to
        in: query
        required: false
        schema:
          type:
          - string
          - number
          description: End time (ISO string or epoch ms)
        description: End time (ISO string or epoch ms)
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum:
          - project
          - org
          description: 'Scope: ''project'' (default, current project) or ''org'' (all projects in account)'
        description: 'Scope: ''project'' (default, current project) or ''org'' (all projects in account)'
      - name: project_id
        in: query
        required: false
        schema:
          type: string
          description: Filter by project ID (optional, for org scope)
        description: Filter by project ID (optional, for org scope)
      - name: workflow_id
        in: query
        required: false
        schema:
          type: string
          description: Filter by workflow / agent run ID
        description: Filter by workflow / agent run ID
      responses:
        '200':
          description: CSV export of raw billable audit events.
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/CostExportCsvResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        '503':
          description: Cost analytics is not available on this deployment, or its model pricing is not synced yet.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - billing:read
      x-vertesia-source:
        file: ../../apps/zeno-server/src/api/cost.ts
        className: CostResource
        methodName: exportCsv
components:
  schemas:
    ModelPricing:
      type: object
      properties:
        model:
          type: string
        provider:
          type: string
        provider_account_id:
          type: string
        service_tier:
          type: string
          description: Processing tier this price applies to
        min_prompt_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: When set, these prices apply to calls whose prompt (input, cached and cache-write tokens) is longer than this many tokens, in place of the prices without it.
        input_price_per_m_tokens:
          type: number
        cached_input_price_per_m_tokens:
          type: number
        cache_write_input_price_per_m_tokens:
          type: number
        output_price_per_m_tokens:
          type: number
        source:
          type: string
          enum:
          - billing_export
          - model_pricing_daily
          - run_time_estimate
          - unavailable
          description: Where the rates come from. `run_time_estimate` rates are the ones recorded on the calls when their cost was estimated; the others come from the pricing catalog.
      required:
      - model
      - input_price_per_m_tokens
      - output_price_per_m_tokens
      - source
      additionalProperties: false
    CostTimeSeriesPoint:
      type: object
      properties:
        timestamp:
          type: string
        cost:
          type: number
        input_tokens:
          type: number
        cached_input_tokens:
          type: number
        cache_write_input_tokens:
          type: number
        output_tokens:
          type: number
        calls:
          type: number
      required:
      - timestamp
      - cost
      - input_tokens
      - output_tokens
      - calls
      additionalProperties: false
    CostByDimension:
      type: object
      properties:
        dimension:
          type: string
        label:
          type: string
        provider:
          type: string
        service_tier:
          type: string
        cost:
          type: number
        input_tokens:
          type: number
        cached_input_tokens:
          type: number
        cache_write_input_tokens:
          type: number
        output_tokens:
          type: number
        calls:
          type: number
        periods:
          type: array
          items:
            $ref: '#/components/schemas/CostTimeSeriesPoint'
      required:
      - dimension
      - cost
      - input_tokens
      - output_tokens
      - calls
      additionalProperties: false
    CostExportCsvResponse:
      type: string
    CostSummary:
      type: object
      properties:
        total_cost:
          type: number
        total_input_tokens:
          type: number
        total_cached_input_tokens:
          type: number
        total_cache_write_input_tokens:
          type: number
        total_output_tokens:
          type: number
        total_calls:
          type: number
        total_duration_ms:
          type: number
      required:
      - total_cost
      - total_input_tokens
      - total_output_tokens
      - total_calls
      - total_duration_ms
      additionalProperties: false
    CostRunPriceQuery:
      type: object
      properties:
        run_id:
          type: string
          description: Interaction execution run ID
        agent_run_id:
          type: string
          description: Agent run ID
        workflow_id:
          type: string
          description: Workflow ID, when known
        workflow_run_id:
          type: string
          description: Temporal workflow run ID, when known
        from:
          type:
          - string
          - number
          description: Optional lower bound for audit events
        to:
          type:
          - string
          - number
          description: Optional upper bound for audit events
        pricing_source:
          type: string
          enum:
          - list
          - historical
          description: Pricing source. Defaults to historical effective prices for run pricing.
        include_comparison_pricing:
          type: boolean
          description: Include the full pricing catalog for cross-model comparison. Defaults to false.
        project_id:
          type: string
          description: Project filter; server fills current project by default
        account_id:
          type: string
          description: Account filter; server fills current account
        scope:
          type: string
          enum:
          - project
          - org
          description: 'Scope: ''project'' (default, current project) or ''org'''
      additionalProperties: false
    CostAnalyticsQuery:
      type: object
      properties:
        from:
          type:
          - string
          - number
          description: Start time (ISO string or epoch ms)
        to:
          type:
          - string
          - number
          description: End time (ISO string or epoch ms)
        group_by:
          type: string
          enum:
          - model
          - environment
          - account
          - project
          - project_tag
          - provider
          - service_tier
          - interaction
          - workflow
          - agent_run
          - workflow_run
          description: Group results by this dimension. `agent_run` groups by root agent run, including the calls of its sub-agents; `workflow_run` groups by Temporal workflow run, which separates each sub-agent.
        resolution:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          description: Time series resolution
        model:
          type: string
          description: Filter by model pattern
        environment_id:
          type: string
          description: Filter by environment ID
        provider:
          type: string
          description: Filter by provider
        service_tier:
          type: string
          description: Filter by resolved processing tier
        project_id:
          type: string
          description: Filter by project ID (optional, for org scope)
        workflow_id:
          type: string
          description: Filter by workflow / agent run ID
        workflow_run_id:
          type: string
          description: Filter by Temporal workflow run ID
        run_id:
          type: string
          description: Filter by interaction execution run ID
        agent_run_id:
          type: string
          description: Filter by agent run ID
        agent_only:
          type: boolean
          description: Restrict usage to agent runs and their attributed nested/background inference. Excludes standalone interactions and non-agent workflows. Defaults to false.
        interaction_id:
          type: string
          description: 'Filter by interaction id: stored ObjectId or namespaced in-code id'
        principal_id:
          type: string
          description: Filter by principal (bare user or API key id; matched against the suffix of principal_id)
        account_id:
          type: string
          description: Filter by account ID (set automatically by server)
        scope:
          type: string
          enum:
          - project
          - org
          description: 'Scope: ''project'' (default, current project) or ''org'' (all projects in account)'
        pricing_source:
          type: string
          enum:
          - list
          - historical
          description: 'Pricing source: ''list'' (latest daily prices) or ''historical'' (daily effective prices over the query range). Default: ''list'''
        no_cache:
          type: boolean
          description: Skip cache and force fresh query
      additionalProperties: false
    CostAnalyticsResponse:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/CostSummary'
        by_dimension:
          type: array
          items:
            $ref: '#/components/schemas/CostByDimension'
        time_series:
          type: array
          items:
            $ref: '#/components/schemas/CostTimeSeriesPoint'
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/ModelPricing'
        pricing_coverage:
          type: object
          properties:
            priced_calls:
              type: number
            unpriced_calls:
              type: number
            assumed_default_calls:
              type: number
            unpriced:
              type: array
              items:
                type: object
                properties:
                  model:
                    type: string
                  provider:
                    type: string
                  service_tier:
                    type: string
                  calls:
                    type: number
                required:
                - model
                - service_tier
                - calls
                additionalProperties: false
            cost_by_source:
              type: object
              properties:
                provider_billed:
                  type: number
                  description: USD the provider reported billing for the calls.
                run_time_estimate:
                  type: number
                  description: USD estimated from list prices when the calls ran, for calls with no billed amount.
                price_table:
                  type: number
                  description: USD computed from the pricing table, for calls with no cost recorded when they ran.
              required:
              - provider_billed
              - run_time_estimate
              - price_table
              additionalProperties: false
              description: How the total cost splits by where each call's cost came from.
          required:
          - priced_calls
          - unpriced_calls
          - assumed_default_calls
          - unpriced
          additionalProperties: false
        query_range:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
          required:
          - from
          - to
          additionalProperties: false
        cached:
          type: boolean
      required:
      - summary
      - by_dimension
      - time_series
      - pricing
      - query_range
      - cached
      additionalProperties: false
    ModelPriceComparisonResponse:
      type: object
      properties:
        prices:
          type: array
          items:
            $ref: '#/components/schemas/ModelPriceComparison'
        effective_range:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
          required:
          - from
          - to
          additionalProperties: false
        list_price_date:
          type: string
      required:
      - prices
      - effective_range
      additionalProperties: false
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    ModelPriceComparison:
      type: object
      properties:
        model:
          type: string
        provider:
          type: string
        provider_account_id:
          type: string
        service_tier:
          type: string
          description: Processing tier this price applies to
        list_price_date:
          type: string
        effective_from:
          type: string
        effective_to:
          type: string
        input_list_price_per_m_tokens:
          type: number
        input_effective_price_per_m_tokens:
          type: number
        cached_input_list_price_per_m_tokens:
          type: number
        cached_input_effective_price_per_m_tokens:
          type: number
        cache_write_input_list_price_per_m_tokens:
          type: number
        cache_write_input_effective_price_per_m_tokens:
          type: number
        output_list_price_per_m_tokens:
          type: number
        output_effective_price_per_m_tokens:
          type: number
        source:
          type: string
          const: model_pricing_daily
      required:
      - model
      - source
      additionalProperties: false
    CostRunPriceResponse:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/CostSummary'
        by_model:
          type: array
          items:
            $ref: '#/components/schemas/CostByDimension'
        pricing:
          type: array
          items:
            $ref: '#/components/schemas/ModelPricing'
        pricing_coverage:
          type: object
          properties:
            priced_calls:
              type: number
            unpriced_calls:
              type: number
            assumed_default_calls:
              type: number
            unpriced:
              type: array
              items:
                type: object
                properties:
                  model:
                    type: string
                  provider:
                    type: string
                  service_tier:
                    type: string
                  calls:
                    type: number
                required:
                - model
                - service_tier
                - calls
                additionalProperties: false
            cost_by_source:
              type: object
              properties:
                provider_billed:
                  type: number
                  description: USD the provider reported billing for the calls.
                run_time_estimate:
                  type: number
                  description: USD estimated from list prices when the calls ran, for calls with no billed amount.
                price_table:
                  type: number
                  description: USD computed from the pricing table, for calls with no cost recorded when they ran.
              required:
              - provider_billed
              - run_time_estimate
              - price_table
              additionalProperties: false
              description: How the total cost splits by where each call's cost came from.
          required:
          - priced_calls
          - unpriced_calls
          - assumed_default_calls
          - unpriced
          additionalProperties: false
        query_range:
          type: object
          properties:
            from:
              type: string
            to:
              type: string
          required:
          - from
          - to
          additionalProperties: false
        pricing_source:
          type: string
          enum:
          - list
          - historical
        matched_events:
          type: number
      required:
      - summary
      - by_model
      - pricing_source
      - matched_events
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections