Cast AI Instance API

openapi: 3.2.0
info:
  title: Reporting Instance API
  version: 0.0.1
  description: Manages cloud instance reporting.
servers:
- url: https://api.cast.ai/
  description: US endpoint
- url: https://api.eu.cast.ai/
  description: EU endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: InstanceAPI
  description: Manages cloud instance reporting.
paths:
  /reporting/v1beta/organizations/{organizationId}/instances:
    get:
      tags:
      - InstanceAPI
      summary: Lists cloud instances with aggregated metrics
      description: Lists cloud instances with aggregated metrics over a time range.
      operationId: InstanceAPI_ListInstances
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: startTime
        in: query
        description: Start time of the reporting period (inclusive).
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: End time of the reporting period (exclusive).
        schema:
          type: string
          format: date-time
      - name: timeZone
        in: query
        description: "Optional time zone in IANA format, e.g., 'Europe/Madrid'.\n Default is Etc/UTC."
        schema:
          type: string
      - name: page.limit
        in: query
        description: Defines the number of items that should be returned
        schema:
          type: string
      - name: page.cursor
        in: query
        description: "Cursor that defines token indicating where to start the next page.\n Empty value indicates to start from beginning of the dataset."
        schema:
          type: string
      - name: regions
        in: query
        description: Filter by regions (e.g., "us-east-1").
        schema:
          type: array
          items:
            type: string
      - name: availabilityZones
        in: query
        description: Filter by availability zones (e.g., "us-east-1a").
        schema:
          type: array
          items:
            type: string
      - name: instanceTypes
        in: query
        description: Filter by instance types (e.g., "m5.xlarge").
        schema:
          type: array
          items:
            type: string
      - name: instanceIds
        in: query
        description: Filter by instance IDs.
        schema:
          type: array
          items:
            type: string
      - name: spot
        in: query
        description: Filter by spot or on-demand lifecycle.
        schema:
          type: boolean
      - name: metrics
        in: query
        description: Metrics to include in the response. If empty, all metrics are returned.
        schema:
          type: array
          items:
            enum:
            - INSTANCE_METRIC_UNSPECIFIED
            - CPU_UTILIZATION_AVG
            - CPU_UTILIZATION_P95
            - CPU_UTILIZATION_MAX
            - MEMORY_UTILIZATION_AVG
            - MEMORY_UTILIZATION_P95
            - MEMORY_UTILIZATION_MAX
            - NETWORK_IN_BYTES
            - NETWORK_OUT_BYTES
            - DISK_READ_OPS
            - DISK_WRITE_OPS
            - EBS_READ_OPS
            - EBS_WRITE_OPS
            - LISTING_COST_HOURLY
            - COST_HOURLY
            - LISTING_COST_TOTAL
            - COST_TOTAL
            type: string
            format: enum
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInstancesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /reporting/v1beta/organizations/{organizationId}/instances-summary:
    get:
      tags:
      - InstanceAPI
      summary: Returns aggregated instance metrics across the filtered fleet
      description: Returns aggregated instance metrics across the filtered fleet.
      operationId: InstanceAPI_GetInstancesSummary
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: startTime
        in: query
        description: Start time of the reporting period (inclusive).
        schema:
          type: string
          format: date-time
      - name: endTime
        in: query
        description: End time of the reporting period (exclusive).
        schema:
          type: string
          format: date-time
      - name: timeZone
        in: query
        description: "Optional time zone in IANA format, e.g., 'Europe/Madrid'.\n Default is Etc/UTC."
        schema:
          type: string
      - name: regions
        in: query
        description: Filter by regions (e.g., "us-east-1").
        schema:
          type: array
          items:
            type: string
      - name: availabilityZones
        in: query
        description: Filter by availability zones (e.g., "us-east-1a").
        schema:
          type: array
          items:
            type: string
      - name: instanceTypes
        in: query
        description: Filter by instance types (e.g., "m5.xlarge").
        schema:
          type: array
          items:
            type: string
      - name: instanceIds
        in: query
        description: Filter by instance IDs.
        schema:
          type: array
          items:
            type: string
      - name: spot
        in: query
        description: Filter by spot or on-demand lifecycle.
        schema:
          type: boolean
      - name: metrics
        in: query
        description: Metrics to include in the response. If empty, all metrics are returned.
        schema:
          type: array
          items:
            enum:
            - INSTANCE_SUMMARY_METRIC_UNSPECIFIED
            - SUMMARY_COST_TOTAL
            - SUMMARY_LISTING_COST_TOTAL
            - SUMMARY_CPU_UTILIZATION_AVG
            - SUMMARY_MEMORY_UTILIZATION_AVG
            - SUMMARY_IDLE_INSTANCES_COUNT
            - SUMMARY_UNDERUTILIZED_INSTANCES_COUNT
            type: string
            format: enum
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstancesSummary'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    ListInstancesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Instance'
          description: List of instances with metrics.
        nextPageCursor:
          type: string
          description: A page cursor to retrieve the next page of results.
        totalCount:
          type: integer
          description: Total count of instances matching the filters.
          format: int32
      description: Response containing instances with their aggregated metrics.
    Instance:
      type: object
      properties:
        instanceId:
          type: string
          description: AWS instance ID (e.g., "i-0abc123def456").
        instanceName:
          type: string
          description: Instance name (from the "Name" tag).
        instanceType:
          type: string
          description: Instance type (e.g., "m5.xlarge").
        cloud:
          type: string
          description: Cloud provider (e.g., "aws").
        region:
          type: string
          description: Region (e.g., "us-east-1").
        availabilityZone:
          type: string
          description: Availability zone name (e.g., "us-east-1a").
        availabilityZoneId:
          type: string
          description: Availability zone ID (e.g., "use1-az1").
        spot:
          type: boolean
          description: Whether the instance runs on spot pricing.
        createTime:
          type: string
          description: When the instance was launched.
          format: date-time
        metrics:
          type: object
          additionalProperties:
            type: number
            format: double
          description: "Aggregated metric values over the requested time range.\n Keys are metric names (e.g., \"cpu_utilization_avg\", \"listing_cost_hourly\").\n Values are aggregated using metric-specific functions (avg, sum, max)."
      description: A cloud instance with aggregated metric values.
    InstancesSummary:
      type: object
      properties:
        totalCount:
          type: integer
          description: Total count of instances matching the filters.
          format: int32
        metrics:
          type: object
          additionalProperties:
            type: number
            format: double
          description: "Aggregated metric values keyed by metric name\n  (e.g. \"cost_total\", \"idle_instances_count\")."
        idleCpuThreshold:
          type: number
          description: CPU% below which an instance is classified as idle (e.g. 1.0).
          format: double
        underutilizedCpuThreshold:
          type: number
          description: "CPU% below which an instance is classified as underutilized (e.g. 30.0).\n Buckets are disjoint: idle = cpu < idle_threshold,\n underutilized = idle_threshold <= cpu < underutilized_threshold."
          format: double
      description: Response containing aggregated fleet-level metrics for summary cards.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-provenance:
  method: searched
  source: https://docs.cast.ai/reference
  harvested: '2026-10-20'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.cast.ai/reference/budgetsapi_createbudget.md
  - https://docs.cast.ai/reference/budgetsapi_deletebudget.md
  - https://docs.cast.ai/reference/budgetsapi_getbudget.md
  - https://docs.cast.ai/reference/budgetsapi_listbudgets.md
  - https://docs.cast.ai/reference/budgetsapi_previewbudgetcost.md
  - https://docs.cast.ai/reference/budgetsapi_updatebudget.md
  - https://docs.cast.ai/reference/clusterscoreapi_getclusterrestrictiondetails.md
  - https://docs.cast.ai/reference/clusterscoreapi_listclusterrestrictions.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_getcontainerlivemigrationdetail.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_getcontainerlivemigrationsummary.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationevents.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationfiltervalues.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationincompatibleworkloads.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrations.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationworkloads.md
  - https://docs.cast.ai/reference/instanceapi_getinstancessummary.md
  - https://docs.cast.ai/reference/instanceapi_listinstances.md
  - https://docs.cast.ai/reference/nodeconditioneventsapi_listnodeconditionevents.md
  - https://docs.cast.ai/reference/nodetemplateapi_getspotinterruptionpredictionperformancesummary.md
  - https://docs.cast.ai/reference/nodetemplateapi_listnodetemplatesmetrics.md
  - https://docs.cast.ai/reference/nodetemplateapi_listnodetemplatesmetricsfiltered.md
  - https://docs.cast.ai/reference/nodetemplateapi_listspotinterruptionpredictionperformancemetrics.md
  - https://docs.cast.ai/reference/optimizationapi_runclusteroptimizationsreport.md
  - https://docs.cast.ai/reference/reliabilitymetricsapi_getclusterreliabilitymetrics.md
  - https://docs.cast.ai/reference/reliabilitymetricsapi_getorganizationclustersreliabilitymetrics.md
  - https://docs.cast.ai/reference/valuerealizationapi_getbaselineparams.md
  - https://docs.cast.ai/reference/valuerealizationapi_recalculatebaselineparams.md
  - https://docs.cast.ai/reference/valuerealizationapi_runclustersvaluerealizationreport.md
  - https://docs.cast.ai/reference/valuerealizationapi_runvaluerealizationtimelinereport.md
  - https://docs.cast.ai/reference/valuerealizationapi_runworkloadsvaluerealizationreport.md
  - https://docs.cast.ai/reference/valuerealizationapi_updatebaselineparams.md
  merge:
    pages: 31
    deduped: 179
    conflicts_kept_first: 0