openapi: 3.2.0
info:
  version: '1'
  title: Elastic Cloud Enterprise Billing Costs Analysis API
  termsOfService: ''
servers:
- url: https://{{hostname}}/api/v1
security:
- basicAuth: []
- apiKey: []
tags:
- name: BillingCostsAnalysis
paths:
  /billing/costs/{organization_id}:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get costs overview for the organization. Currently unavailable in self-hosted ECE.
      description: Retrieves an overview of the costs by organization ID.
      operationId: get-costs-overview
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
        required: false
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: Top-level cost overview for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostsOverview'
        '400':
          description: 'The specified date range is invalid. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'An error occurred when fetching an overview of the costs for the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
  /billing/costs/{organization_id}/charts:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get charts for the organization. Currently unavailable in self-hosted ECE.
      description: Retrieves the usage charts for the organization.
      operationId: get-costs-charts
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
        required: false
        schema:
          type: string
      - name: bucketing_strategy
        in: query
        description: The desired bucketing strategy for the charts. Defaults to `daily`.
        required: false
        schema:
          type: string
          enum:
          - daily
          - monthly
          default: daily
      deprecated: true
      responses:
        '200':
          description: The usage charts of an organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartItems'
        '400':
          description: 'The specified date range is invalid. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '429':
          description: 'Too many requests. (code: `billing_service.rate_limited`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'Error fetching the itemized costs for the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
  /billing/costs/{organization_id}/deployments:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get deployments costs for the organization. Currently unavailable in self-hosted ECE.
      description: Retrieves the costs associated with all deployments for the organization.
      operationId: get-costs-deployments
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch activity. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch activity. Defaults to the current date.
        required: false
        schema:
          type: string
      - name: Accept
        in: header
        description: Accept header containing the content preference.
        required: false
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: The costs associated to a set of products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentsCosts'
        '400':
          description: 'Invalid date range specified. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'An error occurred when fetching the costs associated with all deployments for the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
  /billing/costs/{organization_id}/deployments/{deployment_id}/charts:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get charts by deployment. Currently unavailable in self-hosted ECE.
      description: Retrieves the usage charts for the given  deployment.
      operationId: get-costs-charts-by-deployment
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: deployment_id
        in: path
        description: Id of a Deployment
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
        required: false
        schema:
          type: string
      - name: bucketing_strategy
        in: query
        description: The desired bucketing strategy for the charts. Defaults to `daily`.
        required: false
        schema:
          type: string
          enum:
          - daily
          - monthly
          default: daily
      deprecated: true
      responses:
        '200':
          description: The usage charts of a deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartItems'
        '400':
          description: 'The specified date range is invalid. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '429':
          description: 'Too many requests. (code: `billing_service.rate_limited`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.rate_limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'Error fetching the itemized costs for the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
  /billing/costs/{organization_id}/deployments/{deployment_id}/items:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get itemized costs by deployments. Currently unavailable in self-hosted ECE.
      description: Retrieves the itemized costs for the given deployment.
      operationId: get-costs-items-by-deployment
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: deployment_id
        in: path
        description: Id of a Deployment
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
        required: false
        schema:
          type: string
      - name: Accept
        in: header
        description: Determines the response body format. Can be either application/json or text/csv.
        required: false
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: The costs associated to a set items billed for a single deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsCosts'
        '400':
          description: 'The specified date range is invalid. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: '* The organization was not found. (code: `organization.not_found`)

            * The Elasticsearch cluster was not found. (code: `billing_service.es_cluster_id_not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
                - billing_service.es_cluster_id_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'An error occurred when fetching the itemized costs for the given deployment of the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
  /billing/costs/{organization_id}/items:
    get:
      tags:
      - BillingCostsAnalysis
      summary: Get itemized costs for the organization. Currently unavailable in self-hosted ECE.
      description: Retrieves the itemized costs for the organization.
      operationId: get-costs-items
      parameters:
      - name: organization_id
        in: path
        description: Identifier for the organization
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: A datetime for the beginning of the desired range for which to fetch costs. Defaults to start of current month.
        required: false
        schema:
          type: string
      - name: to
        in: query
        description: A datetime for the end of the desired range for which to fetch costs. Defaults to the current date.
        required: false
        schema:
          type: string
      deprecated: true
      responses:
        '200':
          description: The costs associated to a set of items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemsCosts'
        '400':
          description: 'The specified date range is invalid. (code: `costs.invalid_date_range`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - costs.invalid_date_range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '403':
          description: 'The current user does not have access to the requested organization. (code: `organization.invalid_access`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.invalid_access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '404':
          description: 'Organization not found. (code: `organization.not_found`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - organization.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
        '500':
          description: 'Error fetching the itemized costs for the organization. (code: `billing_service.failed_request`)'
          headers:
            x-cloud-error-codes:
              description: The error codes associated with the response
              schema:
                type: string
                enum:
                - billing_service.failed_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicFailedReply'
      x-doc:
        tag: Billing Costs Analysis
components:
  schemas:
    BasicFailedReplyElement:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: A structured code representing the error type that occurred
        message:
          type: string
          description: A human readable message describing the error that occurred
        fields:
          type: array
          description: If the error can be tied to a specific field or fields in the user request, this lists those fields
          items:
            type: string
    DeploymentCosts:
      type: object
      required:
      - costs
      - deployment_id
      - deployment_name
      - hourly_rate
      properties:
        deployment_id:
          type: string
          description: Elasticsearch deployment id
        deployment_name:
          type: string
          description: Elasticsearch deployment name
        costs:
          description: Costs associated to the deployment
          $ref: '#/components/schemas/Costs'
        hourly_rate:
          type: number
          format: double
          description: Price per hour
        period:
          description: Period
          $ref: '#/components/schemas/Period'
      description: Detailed costs for a deployment for an organization. All of the costs are expressed in Elastic Consumption Unit (ECU).
    BasicFailedReply:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          description: A list of errors that occurred in the failing request
          items:
            $ref: '#/components/schemas/BasicFailedReplyElement'
    Costs:
      type: object
      required:
      - dimensions
      - total
      properties:
        total:
          type: number
          format: double
          description: Total costs
        dimensions:
          type: array
          description: A collection of billing details by dimension.
          items:
            $ref: '#/components/schemas/Dimension'
      description: Costs overview for an organization. All of the costs, credits, trials are expressed in Elastic Consumption Unit (ECU).
    Balance:
      type: object
      required:
      - available
      - line_items
      - remaining
      properties:
        available:
          type: number
          format: double
          description: Available balance
        remaining:
          type: number
          format: double
          description: Remaining balance
        line_items:
          type: array
          description: A collection of order line items for for an organization
          items:
            $ref: '#/components/schemas/SimplifiedLineItem'
      description: The available balance for an organization
    ItemsCosts:
      type: object
      required:
      - costs
      - data_transfer_and_storage
      - resources
      properties:
        costs:
          description: Costs for the Elastic Cloud resources
          $ref: '#/components/schemas/Costs'
        data_transfer_and_storage:
          type: array
          description: List of the detailed costs associated to the Data Transfer and Storage (DTS) dimensions
          items:
            $ref: '#/components/schemas/DtsDimensionCosts'
        resources:
          type: array
          description: Costs of the list of resources
          items:
            $ref: '#/components/schemas/ItemCosts'
      description: Costs associated to a set of Elastic Cloud resources for an organization. All of the costs are expressed in Elastic Consumption Unit (ECU).
    DtsDimensionCosts:
      type: object
      required:
      - cost
      - name
      - quantity
      - rate
      - sku
      - type
      properties:
        cost:
          type: number
          format: double
          description: Costs associated to the Data Transfer and Storage (DTS) dimensions for an organization
        name:
          type: string
          description: DTS dimension name
        quantity:
          description: DTS usage
          $ref: '#/components/schemas/DtsQuantity'
        rate:
          description: Cost per unit
          $ref: '#/components/schemas/DtsRate'
        sku:
          type: string
          description: DTS dimension Stock Keeping Unit (SKU)
        type:
          type: string
          description: Type of the DTS dimension usage
      description: The costs associated to a Data Transfer and Storage (DTS) dimension for an organization. All of the costs, credits, and trials are expressed in Elastic Consumption Units (ECU).
    ChartItemValue:
      type: object
      required:
      - id
      - name
      - value
      properties:
        id:
          type: string
          description: The id of chart item value
        name:
          type: string
          description: The name of the chart item value
        value:
          type: number
          format: double
          description: The actual value of the chart item value
      description: A ChartItem value
    SimplifiedLineItem:
      type: object
      required:
      - ecu_balance
      - ecu_quantity
      - end
      - id
      - start
      properties:
        id:
          type: string
          description: Line Item ID
        ecu_quantity:
          type: number
          format: double
          description: Original Elastic Consumption Unit (ECU) quantity
        ecu_balance:
          type: number
          format: double
          description: Elastic Consumption Unit (ECU) Balance
        start:
          type: string
          format: date-time
          description: Start of the line item's validity
        end:
          type: string
          format: date-time
          description: Expiration of the line item
      description: Line Item
    ItemCosts:
      type: object
      required:
      - hours
      - instance_count
      - kind
      - name
      - period
      - price
      - price_per_hour
      - sku
      properties:
        hours:
          type: integer
          format: int64
          description: Resource usage in hours
        instance_count:
          type: integer
          format: int32
          description: Number of instances
        period:
          description: Period
          $ref: '#/components/schemas/Period'
        kind:
          type: string
          description: Kind of resource
          enum:
          - elasticsearch
          - kibana
          - apm
          - integrations_server
          - appsearch
          - enterprise_search
        price:
          type: number
          format: double
          description: Resource price
        price_per_hour:
          type: number
          format: double
          description: Price per hour
        name:
          type: string
          description: Resource name
        sku:
          type: string
          description: Stock Keeping Unit (SKU)
      description: Detailed costs associated to an Elastic Cloud Resource for an organization. All of the costs are expressed in Elastic Consumption Unit (ECU).
    DeploymentsCosts:
      type: object
      required:
      - deployments
      - total_cost
      properties:
        total_cost:
          type: number
          format: double
          description: Total cost for all deployments
        deployments:
          type: array
          description: Costs of the list of deployments
          items:
            $ref: '#/components/schemas/DeploymentCosts'
      description: Costs associated to a set of deployments for an organization. All of the costs are expressed in Elastic Consumption Unit (ECU).
    Dimension:
      type: object
      required:
      - cost
      - type
      properties:
        type:
          type: string
          description: The type of the billing dimension
          enum:
          - capacity
          - data_in
          - data_internode
          - data_out
          - storage_api
          - storage_bytes
        cost:
          type: number
          format: double
          description: The cost of the billing dimension
      description: Billing dimension
    DtsRate:
      type: object
      required:
      - formatted_value
      - value
      properties:
        value:
          type: number
          format: double
          description: Raw rate
        formatted_value:
          type: string
          description: Rate in human readable format
      description: DTS Rate
    CostsOverview:
      type: object
      required:
      - costs
      - hourly_rate
      - trials
      properties:
        costs:
          description: Costs for the organization
          $ref: '#/components/schemas/Costs'
        trials:
          type: number
          format: double
          description: Trial costs for the organization
        hourly_rate:
          type: number
          format: double
          description: Hourly rate applied.
        balance:
          description: Balance for the organization
          $ref: '#/components/schemas/Balance'
      description: The top level costs overview for an organization. All of the costs, credits, trials are expressed in Elastic Consumption Unit (ECU).
    DtsQuantity:
      type: object
      required:
      - formatted_value
      - value
      properties:
        value:
          type: integer
          format: int64
          description: Raw quantity
        formatted_value:
          type: string
          description: Quantity in human readable format
      description: DTS quantity
    ChartItems:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          description: The list of chart item
          items:
            $ref: '#/components/schemas/ChartItem'
      description: A collection of ChartItems
    Period:
      type: object
      required:
      - end
      - start
      properties:
        start:
          type: string
          format: date-time
          description: Start
        end:
          type: string
          format: date-time
          description: End
      description: Period
    ChartItem:
      type: object
      required:
      - timestamp
      - values
      properties:
        timestamp:
          type: integer
          format: int64
          description: Axis X position
        values:
          type: array
          description: the collection of values to plot the chart item
          items:
            $ref: '#/components/schemas/ChartItemValue'
      description: Chart Item
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
    basicAuth:
      type: http
      scheme: basic
x-elastic:
  curl:
    auth: '-H "Authorization: ApiKey $ECE_API_KEY"'