Mabl Usage API

openapi: 3.2.0
info:
  title: mabl Usage API
  description: APIs for interacting with mabl services
  version: 0.599.3.1792436330
  x-readme-id: 62c896636916ce01d2ff4f5a
servers:
- url: /
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Usage
paths:
  /usage/executions:
    get:
      tags:
      - Usage
      summary: retrieve execution usage
      description: Get a set of execution stats
      operationId: retrieveExecutionUsage
      parameters:
      - name: organization_id
        in: query
        description: The organization id to retrieve metrics for
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: month
        in: query
        description: The metric type to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: year
        in: query
        description: The year to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The stats for this metric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonthlyExecutionUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /usage/annual/executions:
    get:
      tags:
      - Usage
      summary: retrieve execution usage
      description: Get a set of execution stats
      operationId: retrieveAnnualExecutionUsage
      parameters:
      - name: organization_id
        in: query
        description: The organization id to retrieve metrics for
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: month
        in: query
        description: The starting month of yearly time frame to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: year
        in: query
        description: The starting year of yearly time frame to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The stats for this metric.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MonthlyExecutionUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /account/{id}/usage/monthly/executions:
    get:
      tags:
      - Usage
      summary: retrieve execution usage
      description: Get a set of execution stats
      operationId: retrieveMonthlyAccountExecutionUsage
      parameters:
      - name: id
        in: path
        description: The account id to retrieve metrics for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: month
        in: query
        description: The month to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: year
        in: query
        description: The year to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: workspace_id
        in: query
        description: Optional workspace ID to scope results to a single workspace within the account
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: workspace_ids
        in: query
        description: Optional comma-separated list of workspace IDs to scope results within the account. Combined with workspace_id when both are given.
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: The stats for this metric.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceExecutionUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /account/{id}/usage/annual/executions:
    get:
      tags:
      - Usage
      summary: retrieve execution usage
      description: Get a set of execution stats
      operationId: retrieveAnnualAccountExecutionUsage
      parameters:
      - name: id
        in: path
        description: The account id to retrieve metrics for
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: month
        in: query
        description: The starting month of yearly time frame to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: year
        in: query
        description: The starting year of yearly time frame to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The stats for this metric.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceExecutionUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /usage/credits:
    get:
      tags:
      - Usage
      summary: retrieve credit usage for the current billing period
      description: Credit allotment, consumption to date, and cap-enforcement state for a workspace's current billing period
      operationId: retrieveCreditUsage
      parameters:
      - name: organization_id
        in: query
        description: The organization id to retrieve credit usage for
        required: true
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: Credit usage for the workspace's current billing period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceCreditUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /usage/daily/executions:
    get:
      tags:
      - Usage
      summary: retrieve daily execution usage
      description: Get daily execution stats for an org
      operationId: retrieveDailyExecutionUsage
      parameters:
      - name: organization_id
        in: query
        description: The organization id to retrieve metrics for
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: day
        in: query
        description: The year to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: month
        in: query
        description: The metric type to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: year
        in: query
        description: The year to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: The stats for this metric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyExecutionUsage'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Read::Usage
  /usage/daily/executions/{id}:
    put:
      tags:
      - Usage
      summary: write daily execution stats
      description: Get a set of execution stats
      operationId: putDailyExecutionUsage
      parameters:
      - name: id
        in: path
        description: The id to write daily usage stats to
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: The daily execution stats to write
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DailyExecutionUsage'
        required: true
      responses:
        '204':
          description: Successfully written
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::Usage
components:
  schemas:
    MonthlyExecutionUsageDays:
      type: object
      properties:
        day:
          type: integer
          description: The day these execution stats are for
          format: int32
        stats:
          $ref: '#/components/schemas/ExecutionStats'
    MonthlyExecutionUsage:
      type: object
      properties:
        id:
          type: string
          description: The ID of the MonthlyExecutionUsage
        organization_id:
          type: string
          description: The ID of the Organization
        month:
          type: integer
          description: The month this usage data is for
          format: int32
        year:
          type: integer
          description: The year this usage data is for
          format: int32
        interval_start:
          type: integer
          description: interval start time
          format: int64
        interval_end:
          type: integer
          description: interval end time
          format: int64
        days:
          type: array
          description: instances of the metric at a point in time
          items:
            $ref: '#/components/schemas/MonthlyExecutionUsageDays'
      description: Summary of one or more individual metric points
    GuardrailApprovalKind:
      type: string
      description: Who decides a guardrail approval. SELF is decided by the person the agent acts for; WORKSPACE, for an agent acting for an API key, by a workspace owner or editor.
      enum:
      - SELF
      - WORKSPACE
    GuardrailRefusal:
      type: object
      properties:
        id:
          type: string
          description: The id of the guardrail policy that decided the refusal.
        reason:
          type: string
          description: Why the policy refuses the request, written for the person the agent acts for.
        decision_id:
          type: string
          description: The id of this decision in the guardrail decision log.
        action:
          type: string
          description: The action the request was evaluated as, written Verb::Resource (for example Delete::Test), as declared by the operation's x-mabl-action extension.
        policy_source:
          type: string
          description: 'Who set the deciding policy: workspace for a rule the workspace''s owners wrote, account for a rule set for the workspace''s account, mabl_agent_type for the agent type''s ceiling, and mabl_default for mabl''s own defaults.'
        approval:
          description: The approval for this request; present when error_code is approval_required and the approval could be recorded. Without it the request cannot be approved.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalRef'
      description: The guardrail policy that refused an agent request.
    GuardrailApprovalState:
      type: string
      description: Where a guardrail approval stands. PENDING awaits a decision and expires undecided after 24 hours; APPROVED lets the agent repeat the request, as often as it does, for 20 minutes; DENIED refuses the same request for 20 minutes after the decision, after which asking again opens a new approval; CANCELLED means a person withdrew it while pending or revoked it while approved. EXPIRED and CANCELLED are final.
      enum:
      - PENDING
      - APPROVED
      - DENIED
      - EXPIRED
      - CANCELLED
    WorkspaceCreditUsage:
      type: object
      properties:
        organization_id:
          type: string
        cap_enforcement_enabled:
          type: boolean
          description: True when the workspace has opted into enforcement (allocations.enforce_limit) on an explicit credit allocation and is not exempt (e.g. trial). False means the allocation is informational only
        period_start:
          type: integer
          description: Billing period start, epoch millis UTC (inclusive)
          format: int64
        period_end:
          type: integer
          description: Billing period end, epoch millis UTC (exclusive)
          format: int64
        allotment_centicredits:
          type: integer
          description: Effective credit allocation in centicredits. Also absent when no credit allocation is configured for the workspace
          format: int64
        consumed_centicredits:
          type: integer
          description: Centicredits consumed so far this period (near-real-time, ~10 minute lag)
          format: int64
        estimated_in_flight_centicredits:
          type: integer
          description: Estimated centicredits for currently running cloud tests. Also absent when the estimate is temporarily unavailable (e.g. its underlying counts could not be read)
          format: int64
      description: Credit usage for a workspace's current billing period. Usage figures are facts about the workspace and are returned whenever computable, independent of whether cap enforcement applies. All numeric fields are absent when the workspace has no credit model (legacy account), no billing period is computable, or the underlying read failed -- absence is not a statement about configuration.
    ExecutionStats:
      type: object
      properties:
        execution_time_seconds:
          type: integer
          description: Total execution time in seconds
          format: int64
        total_journey_executions:
          type: integer
          description: Count of browser (trained) test (journey) executions
          format: int64
        total_step_executions:
          type: integer
          description: Count of step executions
          format: int64
        total_mobile_test_executions:
          type: integer
          description: Count of mobile test executions
          format: int64
        total_api_step_executions:
          type: integer
          description: Count of API step (browser) executions
          format: int64
        total_api_test_executions:
          type: integer
          description: Count of API test executions
          format: int64
        total_a11y_step_executions:
          type: integer
          description: Count of a11y step executions
          format: int64
        total_adhoc_ai_assertion_executions:
          type: integer
          description: Count of adhoc ai assertions executed
          format: int64
        total_performance_executions:
          type: integer
          description: Count of total performance test executions
          format: int64
        total_performance_used_api_minutes:
          type: integer
          description: Count of total used (actual execution time) API minutes in performance tests
          format: int64
        total_performance_billable_api_minutes:
          type: integer
          description: Count of total billable (used rounded to nearest billing increment) API minutes in performance tests
          format: int64
        total_performance_used_browser_minutes:
          type: integer
          description: Count of total used (actual execution time) browser minutes in performance tests
          format: int64
        total_performance_billable_browser_minutes:
          type: integer
          description: Count of total billable (used rounded to nearest billing increment) browser minutes in performance tests
          format: int64
        total_functional_api_usage_centicredits:
          type: integer
          description: Total usage from functional api test executions in centicredits
          format: int64
        total_functional_browser_usage_centicredits:
          type: integer
          description: Total usage from functional browser test executions in centicredits
          format: int64
        total_functional_mobile_usage_centicredits:
          type: integer
          description: Total usage from functional mobile test executions in centicredits
          format: int64
        total_performance_api_usage_centicredits:
          type: integer
          description: Total usage from performance api test executions in centicredits
          format: int64
        total_performance_browser_usage_centicredits:
          type: integer
          description: Total usage from performance browser test executions in centicredits
          format: int64
        total_adhoc_ai_assertion_usage_millicredits:
          type: integer
          description: Total usage from adhoc ai assertion usage in millicredits
          format: int64
      description: A single daily execution object
    WorkspaceExecutionUsage:
      type: object
      properties:
        organization_id:
          type: string
          description: ID of the organization
        month:
          type: integer
          description: starting month this usage data is for
          format: int32
        year:
          type: integer
          description: starting year this usage data is for
          format: int32
        interval:
          type: string
          description: time interval this usage data is for
          enum:
          - month
          - year
        usage:
          type: array
          description: usage for the given interval
          items:
            $ref: '#/components/schemas/MonthlyExecutionUsage'
    GuardrailApprovalRef:
      type: object
      properties:
        id:
          type: string
          description: The approval's id.
        state:
          description: Where the approval stands.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalState'
        kind:
          description: Who decides the approval.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalKind'
        request_expires_time:
          type: integer
          description: When the approval expires if nobody decides it, in epoch milliseconds.
          format: int64
        url:
          type: string
          description: The mabl app page where a person reviews the approval.
      description: 'An approval a guardrail policy asks for. While it is PENDING, stop: give the person the url, tell them the request is waiting for approval, and do not repeat the request or poll in a loop. Once a person tells you it is APPROVED, repeat the identical request with the header X-Mabl-Approval set to id. DENIED means a person said no, so do not work around it.'
    DailyExecutionUsage:
      type: object
      properties:
        id:
          type: string
          description: The ID of the DailyExecutionUsage
        organization_id:
          type: string
          description: The ID of the Organization
        month:
          type: integer
          description: The month this usage data is for
          format: int32
        year:
          type: integer
          description: The year this usage data is for
          format: int32
        day:
          type: integer
          description: The day the usage data is for
          format: int32
        interval_start:
          type: integer
          description: interval start time
          format: int64
        interval_end:
          type: integer
          description: interval end time
          format: int64
        stats:
          $ref: '#/components/schemas/ExecutionStats'
      description: A single daily execution object
    ErrorResponseGeneric:
      type: object
      properties:
        id:
          type: string
          x-mabl-scope: public
        code:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          x-mabl-scope: public
        message:
          type: string
          x-mabl-scope: public
        error_code:
          type: string
          description: Machine-readable reason for the error, present only when the API names one. Values are guardrail_blocked (a guardrail policy refused an agent request), approval_required (a guardrail policy requires a person to approve the request first).
        guardrail:
          description: The guardrail policy that refused the request; present only when error_code is guardrail_blocked or approval_required.
          allOf:
          - $ref: '#/components/schemas/GuardrailRefusal'
  responses:
    ErrorResponse:
      description: Unknown error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: apiKey
      name: Authorization
      in: header