CloudZero

CloudZero API

The CloudZero API V2 enables you to automate the collection, allocation, and analysis of your infrastructure spend. It provides endpoints for querying billing costs and dimensions, managing insights and budgets, sending unit metric and allocation telemetry data, and ingesting cost data from any source via the AnyCost framework.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.cloudzero.com/reference/introduction

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/openapi/cloudzero-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-schema/cloudzero-cost.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-schema/cloudzero-insight.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-schema/cloudzero-budget.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-schema/cloudzero-telemetry-record.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-schema/cloudzero-billing-drop.json

Other Resources

🔗
Authorization
https://docs.cloudzero.com/reference/authorization
🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/json-ld/cloudzero-context.jsonld
🔗
Spectral
https://raw.githubusercontent.com/api-evangelist/cloudzero/refs/heads/main/rules/cloudzero-rules.yml

OpenAPI Specification

cloudzero-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: CloudZero API
  description: >-
    The CloudZero API V2 enables you to automate the collection, allocation, and
    analysis of your infrastructure spend. It is organized around REST with
    predictable resource-oriented URLs, accepts JSON request bodies, returns JSON
    responses, and uses standard HTTP methods, headers, response codes, and
    authentication.
  version: 2.0.0
  contact:
    name: CloudZero
    url: https://www.cloudzero.com/
  termsOfService: https://www.cloudzero.com/terms-of-service
servers:
  - url: https://api.cloudzero.com
    description: CloudZero Production API
security:
  - apiKey: []
tags:
  - name: Allocation Telemetry
    description: >-
      Send, edit, and delete allocation telemetry data for splitting cloud cost
      data through custom allocation dimensions.
  - name: AnyCost
    description: >-
      Ingest cost data from any source using the AnyCost Stream Adaptor and
      Common Bill Format (CBF).
  - name: Billing
    description: Retrieve cost and dimension data for billing analysis.
  - name: Budgets
    description: Create, read, update, and delete budgets for cost tracking.
  - name: Insights
    description: Create, read, update, and delete cost insights.
  - name: Unit Metric Telemetry
    description: >-
      Send, edit, and delete unit metric telemetry data related to your
      system operations.
paths:
  /v2/billing/costs:
    post:
      operationId: getBillingCosts
      summary: CloudZero Get billing costs
      description: >-
        Returns cost data according to the parameters passed in. Supports
        grouping by Account, Service, and other dimensions with various filters
        and cost types.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start:
                  type: string
                  format: date-time
                  description: Start date for the cost query.
                end:
                  type: string
                  format: date-time
                  description: End date for the cost query.
                group_by:
                  type: array
                  items:
                    type: string
                  description: >-
                    Dimensions to group costs by (e.g., Account, Service,
                    Region).
                filter:
                  type: object
                  description: Filters to apply to the cost query.
                  additionalProperties: true
                granularity:
                  type: string
                  enum:
                    - daily
                    - monthly
                    - cumulative
                  description: Time granularity for the cost data.
                cost_type:
                  type: string
                  enum:
                    - billed
                    - discounted
                    - discounted_amortized
                    - amortized
                    - invoiced_amortized
                    - real
                    - on_demand
                  description: The type of cost data to return.
              required:
                - start
                - end
      responses:
        '200':
          description: Successful response with cost data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        group:
                          type: object
                          additionalProperties:
                            type: string
                        cost:
                          type: array
                          items:
                            type: object
                            properties:
                              timestamp:
                                type: string
                                format: date-time
                              value:
                                type: number
                                format: double
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '429':
          description: Rate limit exceeded.
  /v2/billing/dimensions:
    get:
      operationId: getBillingDimensions
      summary: CloudZero Get billing dimensions
      description: >-
        Returns a list of dimensions available for use in the getBillingCosts
        API and in CostFormation.
      tags:
        - Billing
      responses:
        '200':
          description: Successful response with dimension data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Unique identifier for the dimension.
                        name:
                          type: string
                          description: Display name for the dimension.
                        type:
                          type: string
                          description: The dimension type.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
  /v2/insights:
    get:
      operationId: getInsights
      summary: CloudZero Get all insights
      description: Returns a list of all insights.
      tags:
        - Insights
      parameters:
        - name: page
          in: query
          schema:
            type: integer
          description: Page number for pagination.
        - name: page_size
          in: query
          schema:
            type: integer
          description: Number of results per page.
      responses:
        '200':
          description: Successful response with list of insights.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Insight'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
    post:
      operationId: createInsight
      summary: CloudZero Create a new insight
      description: Creates a new insight for tracking cost anomalies and patterns.
      tags:
        - Insights
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightInput'
      responses:
        '201':
          description: Insight created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Insight'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
  /v2/insights/{insight_id}:
    get:
      operationId: getOneInsight
      summary: CloudZero Get a single insight
      description: Returns a single insight by its identifier.
      tags:
        - Insights
      parameters:
        - name: insight_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the insight.
      responses:
        '200':
          description: Successful response with insight data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Insight'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Insight not found.
    put:
      operationId: updateOneInsight
      summary: CloudZero Update an insight
      description: Updates an existing insight.
      tags:
        - Insights
      parameters:
        - name: insight_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the insight.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightInput'
      responses:
        '200':
          description: Insight updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Insight'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Insight not found.
    delete:
      operationId: deleteOneInsight
      summary: CloudZero Delete an insight
      description: Deletes a single insight by its identifier.
      tags:
        - Insights
      parameters:
        - name: insight_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the insight.
      responses:
        '204':
          description: Insight deleted successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Insight not found.
  /v2/budgets:
    get:
      operationId: getBudgets
      summary: CloudZero Get all budgets
      description: Returns a list of all budgets.
      tags:
        - Budgets
      parameters:
        - name: page
          in: query
          schema:
            type: integer
          description: Page number for pagination.
        - name: page_size
          in: query
          schema:
            type: integer
          description: Number of results per page.
      responses:
        '200':
          description: Successful response with list of budgets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Budget'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
    post:
      operationId: createBudget
      summary: CloudZero Create a new budget
      description: >-
        Creates a new budget linked to a View for tracking spend against
        business metrics.
      tags:
        - Budgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetInput'
      responses:
        '201':
          description: Budget created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Budget'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
  /v2/budgets/{budget_id}:
    get:
      operationId: getOneBudget
      summary: CloudZero Get a single budget
      description: Returns a single budget by its identifier.
      tags:
        - Budgets
      parameters:
        - name: budget_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the budget.
      responses:
        '200':
          description: Successful response with budget data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Budget'
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Budget not found.
    put:
      operationId: updateOneBudget
      summary: CloudZero Update a budget
      description: Updates an existing budget.
      tags:
        - Budgets
      parameters:
        - name: budget_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the budget.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetInput'
      responses:
        '200':
          description: Budget updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Budget'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Budget not found.
    delete:
      operationId: deleteOneBudget
      summary: CloudZero Delete a budget
      description: Deletes a single budget by its identifier.
      tags:
        - Budgets
      parameters:
        - name: budget_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the budget.
      responses:
        '204':
          description: Budget deleted successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '403':
          description: Forbidden.
        '404':
          description: Budget not found.
  /v1/telemetry/{stream_name}/records:
    post:
      operationId: postMetricTelemetry
      summary: CloudZero Post unit metric telemetry records
      description: >-
        Sends unit metric telemetry data related to your system operations.
        The stream name can be used in unit economics calculations.
      tags:
        - Unit Metric Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the telemetry stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/MetricTelemetryRecord'
              required:
                - records
      responses:
        '202':
          description: Telemetry records accepted for processing.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '429':
          description: Rate limit exceeded.
    delete:
      operationId: deleteMetricTelemetry
      summary: CloudZero Delete unit metric telemetry records
      description: >-
        Deletes any data within the appropriate stream that matches the
        supplied properties. Timestamp is minimally required.
      tags:
        - Unit Metric Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the telemetry stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                  description: Timestamp of the records to delete.
                granularity:
                  type: string
                  enum:
                    - HOURLY
                    - DAILY
                    - MONTHLY
                  description: Granularity of the records to delete.
              required:
                - timestamp
      responses:
        '200':
          description: Records deleted successfully.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
  /v1/telemetry/{stream_name}:
    delete:
      operationId: deleteMetricTelemetryStream
      summary: CloudZero Delete a unit metric telemetry stream
      description: Deletes an entire telemetry stream and all associated data.
      tags:
        - Unit Metric Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the telemetry stream to delete.
      responses:
        '204':
          description: Stream deleted successfully.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '404':
          description: Stream not found.
  /v1/telemetry/allocation/{stream_name}/sum:
    post:
      operationId: postAllocationTelemetrySum
      summary: CloudZero Post allocation telemetry records (sum)
      description: >-
        Sends allocation telemetry data that will be summed with any existing
        data at the same timestamp and granularity within the stream.
      tags:
        - Allocation Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the allocation telemetry stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/AllocationTelemetryRecord'
              required:
                - records
      responses:
        '202':
          description: Telemetry records accepted for processing.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '429':
          description: Rate limit exceeded.
  /v1/telemetry/allocation/{stream_name}/replace:
    post:
      operationId: postAllocationTelemetryReplace
      summary: CloudZero Post allocation telemetry records (replace)
      description: >-
        Sends allocation telemetry data that will replace any existing data at
        the same timestamp and granularity within the stream.
      tags:
        - Allocation Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the allocation telemetry stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/AllocationTelemetryRecord'
              required:
                - records
      responses:
        '202':
          description: Telemetry records accepted for processing.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '429':
          description: Rate limit exceeded.
  /v1/telemetry/allocation/{stream_name}/delete:
    post:
      operationId: deleteAllocationTelemetry
      summary: CloudZero Delete allocation telemetry records
      description: >-
        Deletes any allocation data within the appropriate stream that matches
        the supplied properties. Timestamp and granularity are minimally
        required.
      tags:
        - Allocation Telemetry
      parameters:
        - name: stream_name
          in: path
          required: true
          schema:
            type: string
          description: Name of the allocation telemetry stream.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                  description: Timestamp of the records to delete.
                granularity:
                  type: string
                  enum:
                    - HOURLY
                    - DAILY
                    - MONTHLY
                  description: Granularity of the records to delete.
              required:
                - timestamp
                - granularity
      responses:
        '200':
          description: Records deleted successfully.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized. Invalid or missing API key.
  /v2/connections/billing/anycost/{connection_id}/billing_drops:
    post:
      operationId: createAnyCostBillingDrop
      summary: CloudZero Create an AnyCost billing drop
      description: >-
        Sends cost data in Common Bill Format (CBF) to an AnyCost Stream
        connection. The request body must fit within a 5MB JSON limit.
      tags:
        - AnyCost
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier for the AnyCost Stream connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                billing_drops:
                  type: array
                  items:
                    $ref: '#/components/schemas/BillingDrop'
              required:
                - billing_drops
      responses:
        '202':
          description: Billing drop accepted for processing.
        '400':
          description: Bad request. Invalid CBF data.
        '401':
          description: Unauthorized. Invalid or missing API key.
        '413':
          description: Payload too large. Exceeds 5MB limit.
        '429':
          description: Rate limit exceeded.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        API key for authentication. Include your API key directly in the
        Authorization header.
  schemas:
    Pagination:
      type: object
      properties:
        next:
          type: string
          description: URL for the next page of results.
        previous:
          type: string
          description: URL for the previous page of results.
        total:
          type: integer
          description: Total number of results.
    Insight:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the insight.
        name:
          type: string
          description: Display name for the insight.
        description:
          type: string
          description: Description of what the insight tracks.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the insight was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the insight was last updated.
        filters:
          type: object
          additionalProperties: true
          description: Filters applied to the insight.
        group_by:
          type: array
          items:
            type: string
          description: Dimensions used for grouping.
    InsightInput:
      type: object
      properties:
        name:
          type: string
          description: Display name for the insight.
        description:
          type: string
          description: Description of what the insight tracks.
        filters:
          type: object
          additionalProperties: true
          description: Filters to apply to the insight.
        group_by:
          type: array
          items:
            type: string
          description: Dimensions to group by.
      required:
        - name
    Budget:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the budget.
        name:
          type: string
          description: Display name for the budget.
        amount:
          type: number
          format: double
          description: Budget amount.
        period:
          type: string
          enum:
            - monthly
            - quarterly
            - annual
          description: Budget period.
        view_id:
          type: string
          description: Identifier for the linked View.
        notifications:
          type: array
          items:
            type: object
            properties:
              threshold:
                type: number
                format: double
                description: Threshold percentage for notification.
              recipients:
                type: array
                items:
                  type: string
                description: Email addresses for notification recipients.
          description: Notification rules for the budget.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the budget was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the budget was last updated.
    BudgetInput:
      type: object
      properties:
        name:
          type: string
          description: Display name for the budget.
        amount:
          type: number
          format: double
          description: Budget amount.
        period:
          type: string
          enum:
            - monthly
            - quarterly
            - annual
          description: Budget period.
        view_id:
          type: string
          description: Identifier for the linked View.
        notifications:
          type: array
          items:
            type: object
            properties:
              threshold:
                type: number
                format: double
              recipients:
                type: array
                items:
                  type: string
          description: Notification rules for the budget.
      required:
        - name
        - amount
        - period
    MetricTelemetryRecord:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp for the telemetry record.
        value:
          type: number
          format: double
          description: Numeric value for the metric.
        granularity:
          type: string
          enum:
            - HOURLY
            - DAILY
            - MONTHLY
          description: Time granularity of the record.
        filter:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs for filtering and grouping.
      required:
        - timestamp
        - value
        - granularity
    AllocationTelemetryRecord:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp for the telemetry record.
        value:
          type: number
          format: double
          description: Numeric value for the allocation.
        granularity:
          type: string
          enum:
            - HOURLY
            - DAILY
            - MONTHLY
          description: Time granularity of the record.
        element:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs identifying the element being allocated.
      required:
        - timestamp
        - value
        - granularity
    BillingDrop:
      type: object
      description: >-
        Cost data in CloudZero Common Bill Format (CBF) for ingestion via
        AnyCost Stream.
      properties:
        line_items:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
                description: Timestamp for the billing line item.
              cost:
                type: number
                format: double
                description: Cost amount for the line item.
              service:
                type: string
                description: Service name associated with the cost.
              description:
                type: string
                description: Description of the cost line item.
              metadata:
                type: object
                additionalProperties:
                  type: string
                description: Additional metadata for the line item.
            required:
              - timestamp
              - cost
      required:
        - line_items