openapi: 3.2.0
info:
  title: DoiT Reports API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Reports
  description: Manage Cloud Analytics reports and get reports data in JSON format.
paths:
  /analytics/v1/reports:
    get:
      tags:
      - Reports
      summary: List reports
      description: 'Returns a list of all Cloud Analytics reports that your account has access to.

        Reports are returned in reverse chronological order by default.'
      operationId: listReports
      parameters:
      - $ref: '#/components/parameters/maxResults'
      - $ref: '#/components/parameters/pageToken'
      - name: filter
        in: query
        description: 'An expression for filtering the results.

          The syntax is `key:[<value>]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters).

          Possible filter keys: **reportName**, **owner**, **type**, **updateTime**, **folderId**'
        example: reportName:This Month vs. Last
        schema:
          type: string
      - name: minCreationTime
        in: query
        description: Min value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created after or at this timestamp are returned.
        schema:
          type: string
      - name: maxCreationTime
        in: query
        description: Max value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created before or at this timestamp are returned.
        schema:
          type: string
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      tags:
      - Reports
      summary: Create a report
      description: Creates a new report.
      operationId: createReport
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Report name.
                  example: A test report by API
                description:
                  type: string
                  description: Report description.
                  example: Cost breakdown by service in the last 3 months
                config:
                  $ref: '#/components/schemas/ExternalConfig'
                labels:
                  type: array
                  items:
                    type: string
                  description: Array of label IDs assigned to the report
                folderId:
                  type: string
                  description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder).
                  default: root
                  example: root
            example:
              name: monthly-cost-by-service
              description: Monthly cost grouped by service
              config:
                includeSubtotals: false
                sortGroups: asc
                sortDimensions: desc
                metrics:
                - type: basic
                  value: cost
                timeRange:
                  amount: 7
                  includeCurrent: false
                  mode: last
                  unit: day
                aggregation: total
                dimensions:
                - id: service_description
                  type: fixed
                displayValues: actuals_only
                timeInterval: day
      responses:
        '201':
          description: Created - The request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalReport'
          links:
            getReport:
              operationId: getReport
              parameters:
                id: $response.body#/id
            updateReport:
              operationId: updateReport
              parameters:
                id: $response.body#/id
            deleteReport:
              operationId: deleteReport
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      x-codegen-request-body-name: Body
  /analytics/v1/reports/query:
    post:
      tags:
      - Reports
      summary: Run a query
      description: 'Runs a report query with the specified configuration without persisting it.

        Fields that are not populated will use their default values if needed.'
      operationId: query
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  $ref: '#/components/schemas/ExternalConfig'
            example:
              config:
                dataSource: billing
                metrics:
                - type: basic
                  value: cost
                timeRange:
                  amount: 30
                  includeCurrent: false
                  mode: last
                  unit: day
                group:
                - id: service_description
                  type: fixed
                timeInterval: day
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunReportResult'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      x-codegen-request-body-name: Body
  /analytics/v1/reports/{id}:
    get:
      tags:
      - Reports
      summary: Get report results
      description: Returns the results of the specified report.
      operationId: getReport
      parameters:
      - $ref: '#/components/parameters/reportId'
      - name: timeRange
        in: query
        description: An optional parameter to override the report time settings. Value should be represented in the format P[n]Y[n]M[n]D[n]. In the representations, the [n] is replaced by the value for each of the date and time elements that follow the [n].
        schema:
          type: string
          pattern: ^P(\d+Y)?(\d+M)?(\d+D)?$
          example: P7D
      - name: startDate
        in: query
        description: 'An optional parameter to override the report time settings. Must be provided together with endDate. Format: yyyy-mm-dd'
        schema:
          type: string
          format: date
          example: '2025-01-01'
      - name: endDate
        in: query
        description: 'An optional parameter to override the report time settings. Must be provided together with startDate. Format: yyyy-mm-dd'
        schema:
          type: string
          format: date
          example: '2025-01-31'
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReportResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
    delete:
      tags:
      - Reports
      summary: Delete a report
      description: Deletes the specified Cloud Analytics report.
      operationId: deleteReport
      parameters:
      - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: OK - Report deleted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
              example: {}
          links:
            listReports:
              operationId: listReports
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    patch:
      tags:
      - Reports
      summary: Update a report
      description: 'Updates a report with the specified configuration.


        Only specified fields will be updated.'
      operationId: updateReport
      parameters:
      - $ref: '#/components/parameters/reportId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalUpdateReport'
        required: false
      responses:
        '200':
          description: OK - Report updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalReport'
          links:
            getReport:
              operationId: getReport
              parameters:
                id: $response.body#/id
            deleteReport:
              operationId: deleteReport
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      x-codegen-request-body-name: Body
  /analytics/v1/reports/{id}/config:
    get:
      tags:
      - Reports
      summary: Get report config
      description: Returns the configuration of the specified Cloud Analytics report.
      operationId: getReportConfig
      parameters:
      - $ref: '#/components/parameters/reportId'
      responses:
        '200':
          description: OK - Report configuration returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalReport'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error - Something went wrong with the DoiT API server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '429':
      description: Too Many Requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ExternalSplit:
      type: object
      description: Specification of how to split costs.
      properties:
        id:
          type: string
          description: ID of the field to split.
        includeOrigin:
          type: boolean
          description: Indicate whether to include the origin.
        mode:
          type: string
          enum:
          - even
          - custom
          - proportional
        origin:
          $ref: '#/components/schemas/ExternalOrigin'
        targets:
          type: array
          description: Targets for the split.
          items:
            $ref: '#/components/schemas/ExternalSplitTarget'
        type:
          type: string
          description: Type of the split.
          example: attribution_group
          enum:
          - datetime
          - fixed
          - optional
          - label
          - tag
          - project_label
          - system_label
          - attribution
          - attribution_group
          - gke
          - gke_label
    Report:
      type: object
      description: Report metadata and the console URL.
      properties:
        id:
          type: string
          description: Report ID.
        reportName:
          type: string
          description: The name of the report.
        owner:
          type: string
          description: Email address of the report owner.
        type:
          type: string
          enum:
          - custom
          - preset
        createTime:
          type: integer
          description: The creation time of the report, in milliseconds since the epoch.
          format: int64
        updateTime:
          type: integer
          description: The time when this report was last updated, in milliseconds since the epoch.
          format: int64
        urlUI:
          type: string
          description: The URL of the report in DoiT console.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelInfo'
          description: List of labels associated with the report.
    AdvancedAnalysis:
      type: object
      description: Advanced analysis options. Each can be set independently.
      properties:
        forecast:
          type: boolean
        notTrending:
          type: boolean
        trendingDown:
          type: boolean
        trendingUp:
          type: boolean
    ExternalConfigMetricFilter:
      description: Metric filter to limit report rows by metric value.
      type: object
      required:
      - metric
      - operator
      - values
      properties:
        metric:
          $ref: '#/components/schemas/ExternalMetric'
        operator:
          description: 'Comparison operator for filtering metric values. Uses short names (`gt`, `gte`, …).

            `limitByChange.operator` uses SQL-style symbols (`>`, `>=`, …) instead.'
          type: string
          enum:
          - gt
          - lt
          - lte
          - gte
          - b
          - nb
          - e
          - ne
        values:
          type: array
          items:
            type: number
            format: double
        operand:
          type: string
          description: 'Whether the threshold applies to each value (default) or the series total.

            Same field as the DoiT Console metric filter `operand` (`OperandSingleValue` /

            `OperandSeriesTotal`). On input, omitted defaults to `single_value`. GET responses

            echo the effective value (`single_value` or `series_total`).'
          enum:
          - single_value
          - series_total
          default: single_value
      example:
        metric:
          type: basic
          value: cost
        operator: gt
        values:
        - 50
    ExternalLimitByChange:
      description: 'Limit by change filter. A report may configure at most two of

        `metricFilter`, `limitByChange`, and top/bottom `group` limits — not all three.'
      type: object
      required:
      - metric
      - changeType
      - operator
      - values
      - includeIncompleteData
      properties:
        metric:
          $ref: '#/components/schemas/ExternalMetric'
        changeType:
          type: string
          enum:
          - percentage
          - absolute
        operator:
          type: string
          description: Comparison operator for period-over-period deltas.
          enum:
          - '>'
          - '>='
          - <
          - <=
          - between
          - not_between
        values:
          type: array
          description: 'Threshold value(s). Unary operators use one entry; `between` and `not_between`

            require two ordered entries.'
          items:
            type: number
            format: double
        includeIncompleteData:
          type: boolean
          description: When true, keeps rows whose deltas could not be evaluated.
      example:
        metric:
          type: basic
          value: cost
        changeType: percentage
        operator: '>='
        values:
        - 50
        includeIncompleteData: false
    ExternalConfig:
      type: object
      description: Report configuration.
      properties:
        metric:
          deprecated: true
          description: 'Deprecated: Use ''metrics'' instead.'
          allOf:
          - $ref: '#/components/schemas/ExternalMetric'
        metrics:
          type: array
          description: The list of metrics to apply to the report. Custom metric can be used only once. Maximum number of metrics is 4.
          items:
            $ref: '#/components/schemas/ExternalMetric'
        metricFilter:
          $ref: '#/components/schemas/ExternalConfigMetricFilter'
        limitAggregation:
          type: string
          description: 'Controls how rows excluded by limits are rendered. Applies when any limit type is active

            (`metricFilter`, `limitByChange`, or a `group` entry with a `limit`). A report may configure

            at most two of those three limit types — not all three. When `displayValues` is not

            `actuals_only`, this field must be `none` (or omitted, which defaults to `none`).'
          enum:
          - none
          - top
          - all
          default: none
        limitByChange:
          $ref: '#/components/schemas/ExternalLimitByChange'
        aggregation:
          description: How to aggregate data values in the report.
          type: string
          enum:
          - total
          - percent_total
          - percent_col
          - percent_row
          - total_over_total
          - count
        advancedAnalysis:
          $ref: '#/components/schemas/AdvancedAnalysis'
        forecastSettings:
          allOf:
          - $ref: '#/components/schemas/ExternalForecastSettings'
          description: Forecast configuration. On PATCH, omit to preserve existing settings; send null to clear/disable forecasting.
        timeInterval:
          description: Time interval for grouping data in the report.
          type: string
          enum:
          - hour
          - day
          - dayCumSum
          - week
          - isoweek
          - month
          - quarter
          - year
          - week_day
        dimensions:
          description: See [Dimensions](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#dimensions).
          type: array
          items:
            $ref: '#/components/schemas/Dimension'
        timeRange:
          $ref: '#/components/schemas/TimeSettings'
        secondaryTimeRange:
          $ref: '#/components/schemas/TimeSettingsSecondary'
        includePromotionalCredits:
          type: boolean
          description: 'Whether to include [promotional credits](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#promotional-credits).

            If set to **true**, the report must use time interval `month`, `quarter`, or `year`.'
        includeSubtotals:
          type: boolean
          description: Whether to include subgroup totals in the report. This option has no impact when reading a report via API.
          default: false
        filters:
          type: array
          description: The filters to apply to the report.
          items:
            $ref: '#/components/schemas/ExternalConfigFilter'
        group:
          type: array
          description: The rows that appear in the tabular format of the report. See [Group by](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#group-by).
          items:
            $ref: '#/components/schemas/Group'
        layout:
          $ref: '#/components/schemas/ExternalRenderer'
        displayValues:
          type: string
          description: See [View data as (Comparative report)](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#view-as).
          enum:
          - actuals_only
          - absolute_change
          - percentage_change
          - absolute_and_percentage
        currency:
          $ref: '#/components/schemas/Currency'
        sortGroups:
          type: string
          default: asc
          enum:
          - asc
          - desc
          - a_to_z
          description: This option has no impact when reading reports via API.
        sortDimensions:
          type: string
          default: desc
          enum:
          - asc
          - desc
          - a_to_z
          description: This option has no impact when reading reports via API.
        dataSource:
          type: string
          description: Data source of the report.
          enum:
          - billing
          - bqlens
          - billing-datahub
          - kubernetes-utilization
        splits:
          type: array
          description: The splits to use in the report.
          items:
            $ref: '#/components/schemas/ExternalSplit'
        displaySettings:
          $ref: '#/components/schemas/ExternalDisplaySettings'
        customTimeRange:
          description: Required when the time range is set to "custom".
          type: object
          properties:
            from:
              type: string
              format: date-time
              description: The start timestamp of the time range in RFC3339 format.
              example: '2024-03-10T23:00:00Z'
            to:
              type: string
              format: date-time
              description: The end timestamp of the time range in RFC3339 format.
              example: '2024-03-12T23:00:00Z'
        count:
          type: object
          description: The field to count distinct values of. Only applicable when aggregation is set to "count".
          required:
          - id
          - type
          properties:
            id:
              type: string
              description: The field identifier to count distinct values of.
            type:
              type: string
              enum:
              - fixed
              - label
              - tag
              - project_label
              - system_label
              description: The metadata field type.
      example:
        metrics:
        - type: basic
          value: cost
        - type: basic
          value: usage
        - type: extended
          value: amortized_cost
        metricFilter:
          metric:
            type: basic
            value: cost
          operator: nb
          values:
          - -1
          - 1
          operand: series_total
        limitAggregation: top
        limitByChange:
          metric:
            type: basic
            value: cost
          changeType: percentage
          operator: '>='
          values:
          - 50
        aggregation: total
        advancedAnalysis:
          forecast: false
          notTrending: false
          trendingDown: false
          trendingUp: false
        forecastSettings:
          mode: totals
          futureTimeIntervals: 3
        timeInterval: month
        dimensions:
        - id: year
          type: datetime
        - id: month
          type: datetime
        timeRange:
          amount: 3
          includeCurrent: false
          mode: last
          unit: month
        includePromotionalCredits: false
        includeSubtotals: false
        filters:
        - id: attribution
          type: attribution
          values:
          - RB8DndcxODriK83IBXXf
          - D7r4znsTj2UC95zGnunW
          inverse: true
        - id: cloud_provider
          type: fixed
          values:
          - amazon-web-services
          - google-cloud
          - microsoft-azure
        group:
        - id: service_description
          limit:
            metric:
              type: basic
              value: cost
            sort: a_to_z
            value: 0
          type: fixed
        layout: table
        displayValues: actuals_only
        currency: USD
        sortGroups: a_to_z
        sortDimensions: a_to_z
        dataSource: billing
    LabelInfo:
      required:
      - id
      - name
      type: object
      description: Metadata for a label.
      properties:
        id:
          type: string
          description: The unique identifier of the label.
        name:
          type: string
          description: The name of the label.
    ExternalMetric:
      description: Metric selector used in reports and filters.
      type: object
      required:
      - type
      - value
      properties:
        type:
          description: Type of metric to use.
          type: string
          enum:
          - basic
          - custom
          - extended
        value:
          type: string
          description: 'For basic metrics, the value can be one of: ["cost", "usage", "savings"]

            If using custom metrics, the value must refer to an existing custom metric ID.'
      example:
        type: basic
        value: cost
    GetReportResponse:
      type: object
      description: Results returned when running a report; includes schema and rows.
      properties:
        id:
          type: string
          description: Report ID.
        reportName:
          type: string
          description: The name of the report.
        owner:
          type: string
          description: Email address of the report owner.
        type:
          type: string
          enum:
          - custom
          - preset
        createTime:
          type: integer
          description: The creation time of the report, in milliseconds since the epoch.
          format: int64
        updateTime:
          type: integer
          description: The time when this report was last updated, in milliseconds since the epoch.
          format: int64
        urlUI:
          type: string
          description: The URL of the report in DoiT console.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelInfo'
          description: List of labels associated with the report.
        result:
          type: object
          properties:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SchemaField'
            mlFeatures:
              type: array
              items:
                type: string
                enum:
                - increasing
                - decreasing
                - none
                - forecast
            rows:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            secondaryRows:
              type: array
              description: Secondary time range rows.
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            forecastRows:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            cacheHit:
              type: boolean
              description: If true, results were fetched from the cache.
    ExternalForecastSettings:
      type: object
      description: 'Settings for cost forecasting on the report.

        Historical fields choose which past data the model learns from.

        Future fields choose how far ahead predicted costs are projected.

        When a custom date range is set for a side, it takes precedence over the corresponding interval count.

        futureCustomDateRange is converted to futureTimeIntervals using the report timeInterval.

        Providing forecastSettings enables forecast (advancedAnalysis.forecast) automatically.

        On PATCH, omit forecastSettings to leave forecasting unchanged; send forecastSettings: null to clear/disable forecasting

        (also removes the forecast feature flag). An empty object enables forecast with default mode totals.

        Interval counts outside the allowed min/max for the report timeInterval are rejected with a validation error that includes the allowed range.'
      properties:
        mode:
          type: string
          description: Forecast granularity mode.
          enum:
          - totals
          - grouping
          default: totals
        historicalTimeIntervals:
          type: integer
          format: int64
          description: 'How many past timeInterval periods of data the model learns from.

            Allowed ranges by timeInterval: hour 2-1000, day 2-500, week 2-100, month 2-36, quarter 2-12, year 2-6.'
        futureTimeIntervals:
          type: integer
          format: int64
          description: 'How many future timeInterval periods of predicted costs to project.

            Allowed ranges by timeInterval: hour 1-1000, day 1-100, week 1-52, month 1-12, quarter 1-4, year 1-3.'
        historicalCustomDateRange:
          description: Past date range of billed data the model learns from. Takes precedence over historicalTimeIntervals.
          allOf:
          - $ref: '#/components/schemas/ExternalForecastDateRange'
        futureCustomDateRange:
          description: 'Date range for how far ahead to project predicted costs. Takes precedence over futureTimeIntervals.

            The range must resolve to a futureTimeIntervals count within the allowed min/max for the report timeInterval.'
          allOf:
          - $ref: '#/components/schemas/ExternalForecastDateRange'
      example:
        mode: totals
        futureCustomDateRange:
          from: '2026-07-10T00:00:00Z'
          to: '2026-09-30T23:59:59Z'
    ExternalReport:
      required:
      - name
      type: object
      description: Configuration and metadata of a stored report.
      properties:
        id:
          type: string
          description: Report ID.
        name:
          type: string
          description: Report name.
        description:
          type: string
          description: Report description.
        type:
          type: string
          description: Report type.
          enum:
          - custom
          - preset
          - managed
        config:
          $ref: '#/components/schemas/ExternalConfig'
        labels:
          type: array
          items:
            type: string
          description: Array of label IDs assigned to the report
        folderId:
          type: string
          description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder).
          default: root
          example: root
    Value:
      description: The content of a single cell from a BigQuery result. Can be a string, number, or null.
      oneOf:
      - type: string
      - type: number
      - type: integer
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    ExternalConfigFilter:
      description: 'To include or exclude certain values.

        When using allocation rules as a filter, both the type and the ID must be "allocation_rule", and the values array contains the allocation rule IDs.

        When using allocations as a filter, the type must be "allocation" and the ID is the actual allocation group ID.'
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: 'Dimension key to filter on. Must pair with `type` and match a dimension returned by `GET /analytics/v1/dimensions` (for example, `service_description` with `type: fixed`). For `allocation_rule`, use `allocation_rule`. For `allocation`, use the allocation group ID. See `DimensionsTypes` for how each `type` uses `id`.'
        type:
          $ref: '#/components/schemas/DimensionsTypes'
        values:
          type: array
          description: List of values to include or exclude. Must match exact strings from your billing or DataHub data for the dimension (for example, `Amazon Simple Storage Service` for AWS S3 on `service_description`). For `allocation_rule`, use allocation rule IDs.
          items:
            type: string
        mode:
          type: string
          description: Controls how the dimension’s `values` are matched when the alert query runs. If mode is omitted, behavior defaults to is.
          enum:
          - is
          - starts_with
          - ends_with
          - contains
          - regexp
          x-enumDescriptions:
            is: Exact match on one or more values.
            starts_with: Value starts with the given string(s).
            ends_with: Value ends with the given string(s).
            contains: Value contains the given string(s).
            regexp: Value matches the regular expression in `values` (exactly one pattern).
        inverse:
          type: boolean
          description: Set to `true` to exclude the set values. If inverse is omitted, behavior defaults to `false`.
        caseInsensitive:
          type: boolean
          description: If true, string matching is case-insensitive. Effective only for starts_with, ends_with, and contains modes; ignored otherwise.
          default: false
        includeNull:
          type: boolean
          description: Include rows where the dimension is null. If includeNull is omitted, behavior defaults to `false`.
          default: false
      example:
        id: cloud_provider
        type: fixed
        inverse: false
        values:
        - google-cloud
    ReportList:
      type: object
      description: List of reports.
      properties:
        pageToken:
          type: string
          description: Page token. It is used to request a specific page of the list results.
        rowCount:
          type: integer
          description: The number of returned records.
          format: int64
          example: 5
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
    DimensionsTypes:
      description: Dimension filter type. Always pair `type` with `id` on scope filters. Discover valid `id` + `type` pairs for your account with `GET /analytics/v1/dimensions`. `allocation_rule` replaces `attribution`; `allocation` replaces `attribution_group`.
      type: string
      enum:
      - datetime
      - fixed
      - optional
      - label
      - tag
      - project_label
      - system_label
      - attribution
      - attribution_group
      - allocation
      - allocation_rule
      - gke
      - gke_label
      x-enumDescriptions:
        fixed: Standard built-in billing dimensions (Service, Provider, Project/Account ID, SKU, Region, etc.).
        label: Customer-defined resource labels; id is the label key, values are label values.
        tag: AWS cost allocation tags; id is the tag key.
        project_label: Google Cloud project-level labels; id is the label key.
        system_label: DoiT- or provider-generated system labels; id is the system label key.
        optional: Console grouping for label/tag keys; use label, tag, project_label, or system_label in API scopes.
        datetime: Time dimensions (Year, Month, Day) for date-based filtering or grouping.
        allocation_rule: Allocation rule filter; id must be allocation_rule, values are rule IDs.
        allocation: Allocation group filter; id is the allocation group ID.
        gke: Google Kubernetes Engine cost-allocation dimensions.
        gke_label: GKE workload labels; id is the label key.
        attribution: Deprecated. Use allocation_rule.
        attribution_group: Deprecated. Use allocation.
    Group:
      description: The dimension that defines a row in the report.
      type: object
      properties:
        id:
          type: string
          description: Dimension ID.
          example: service_description
        limit:
          $ref: '#/components/schemas/Limit'
        type:
          $ref: '#/components/schemas/DimensionsTypes'
      example:
        id: service_description
        type: fixed
        limit:
          value: 3
          sort: desc
          metric:
            type: basic
            value: cost
    SchemaField:
      type: object
      description: Schema of a report result column.
      properties:
        name:
          type: string
        type:
          type: string
    ExternalOrigin:
      type: object
      description: Origin info for cost splitting.
      properties:
        id:
          type: string
          description: ID of the origin.
        type:
          type: string
          description: Type of the origin.
          example: attribution
          enum:
          - datetime
          - fixed
          - optional
          - label
          - tag
          - project_label
          - system_label
          - attribution
          - attribution_group
          - gke
          - gke_label
          - unallocated
    TimeSettings:
      type: object
      description: 'Specify a predefined or custom time range for the report.

        For example, to specify a custom time range of "last 2 days", set the mode to `last`, the amount to `2`, and the unit to `day`. If `includeCurrent` is `true`, the range will be yesterday and today; otherwise, the range will be yesterday and the day before yesterday.

        If "custom" type is specified, you need to provide a custom time range in the `customTimeRange` field.'
      properties:
        amount:
          description: Number of time units to include in the time range.
          maximum: 5000
          minimum: 0
          type: integer
          format: int64
        includeCurrent:
          description: Whether to include the current time period.
          type: boolean
        mode:
          description: Time range mode (last N periods, current period, or custom).
          type: string
          enum:
          - last
          - current
          - custom
        unit:
          description: Time unit for the time range.
          type: string
          enum:
          - day
          - week
          - month
          - quarter
          - year
      example:
        amount: 3
        includeCurrent: false
        mode: last
        unit: month
    ExternalForecastDateRange:
      type: object
      description: Start and end timestamps in RFC3339 format.
      properties:
        from:
          type: string
          format: date-time
          description: Start timestamp in RFC3339 format.
          example: '2026-07-10T00:00:00Z'
        to:
          type: string
          format: date-time
          description: End timestamp in RFC3339 format.
          example: '2026-09-30T23:59:59Z'
    ExternalDisplaySettings:
      type: object
      description: Display settings for the report.
      properties:
        themeId:
          type: string
          default: default
          description: 'Identifier of the theme applied to the report. The reserved

            sentinel `"default"` is returned on GET when no theme is stored

            and clears the stored value on PATCH. Omit the field on PATCH

            to leave the stored value unchanged.'
        dataLabelFontSize:
          type: string
          description: Font size used for data labels on charts.
          enum:
          - auto
          - small
          - medium
          - large
        axisLabelFontSize:
          type: string
          description: Font size used for axis labels on charts.
          enum:
          - auto
          - small
          - medium
          - large
        numberScale:
          type: string
          description: Scale applied to numeric values when rendering the report.
          enum:
          - auto
          - thousands
          - millions
          - billions
          - raw
        decimalPrecision:
          type: integer
          minimum: 0
          maximum: 8
          description: Number of decimal places shown for numeric values.
    ExternalRenderer:
      type: string
      description: Type of visualization or output format.
      enum:
      - column_chart
      - stacked_column_chart
      - bar_chart
      - stacked_bar_chart
      - line_chart
      - spline_chart
      - area_chart
      - area_spline_chart
      - stacked_area_chart
      - treemap_chart
      - table
      - table_heatmap
      - table_row_heatmap
      - table_col_heatmap
      - csv_export
      - sheets_export
    TimeSettingsSecondary:
      type: object
      description: Secondary time range for comparative reports.
      properties:
        amount:
          description: Number of periods to shift back.
          type: integer
          format: int64
        includeCurrent:
          description: "Whether to align to complete previous periods (full year/quarter/month) vs shifting dates by amount.\n    When `true`, selects complete periods (e.g., full previous year Jan 1-Dec 31, not up to today).\n    When `false`, shifts dates by amount, which may result in partial periods extending to today."
          type: boolean
        unit:
          description: Time interval unit for shifting.
          type: string
          enum:
          - day
          - month
          - quarter
          - year
        customTimeRange:
          description: Custom date range for the secondary time range.
          type: object
          properties:
            from:
              type: string
              format: date-time
              description: Start date.
            to:
              type: string
              format: date-time
              description: End date.
      example:
        amount: 1
        includeCurrent: false
        unit: year
    Limit:
      type: object
      description: To limit the number of results based on ranking. See [Limit by top/bottom](https://help.doit.com/docs/cloud-analytics/reports/editing-your-cloud-report#limit-by-topbottom).
      required:
      - metric
      properties:
        metric:
          $ref: '#/components/schemas/ExternalMetric'
        sort:
          description: Sort order for ranking results.
          type: string
          enum:
          - a_to_z
          - asc
          - desc
        value:
          type: integer
          description: The number of items to show
          format: int64
      example:
        value: 3
        sort: desc
        metric:
          type: basic
          value: cost
    ExternalSplitTarget:
      type: object
      description: Target and value of a split definition.
      properties:
        id:
          type: string
          description: ID of the target.
        type:
          type: string
          description: 'Type of the target.

            If split type is "attribution_group", then target type must be "attribution".

            Otherwise split types and target types must be the same.'
          example: attribution
          enum:
          - datetime
          - fixed
          - optional
          - label
          - tag
          - project_label
          - system_label
          - attribution
          - attribution_group
          - gke
          - gke_label
        value:
          type: number
          description: Percent of the target, represented in float format. E.g. 30% is 0.3. Required only if the Split Mode is custom.
          format: double
    ExternalUpdateReport:
      type: object
      description: Partial report object used for updates.
      properties:
        config:
          $ref: '#/components/schemas/ExternalConfig'
        description:
          type: string
          description: Report description
        name:
          type: string
          description: Report name
        labels:
          type: array
          items:
            type: string
          description: Array of label IDs assigned to the report
        folderId:
          type: string
          description: Identifier of the folder that contains the report. Set to "root" if the report is at the top level (not in a folder).
          default: root
          example: root
      example:
        config:
          timeRange:
            amount: 1
            includeCurrent: false
            mode: last
            unit: month
          timeInterval: week
        description: An update via API
        name: A new name
    Dimension:
      description: Definition of a report dimension.
      type: object
      properties:
        id:
          type: string
          description: The identifier of the dimension.
        type:
          $ref: '#/components/schemas/DimensionsTypes'
      example:
        id: sku_description
        type: fixed
    Currency:
      description: Currency code for monetary values.
      type: string
      enum:
      - USD
      - ILS
      - EUR
      - AUD
      - CAD
      - GBP
      - DKK
      - NOK
      - SEK
      - BRL
      - SGD
      - MXN
      - CHF
      - MYR
      - TWD
      - EGP
      - ZAR
      - JPY
      - IDR
      - AED
      - THB
      - COP
    RunReportResult:
      type: object
      description: Results returned when running a report; includes schema and rows.
      properties:
        result:
          type: object
          properties:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SchemaField'
            mlFeatures:
              type: array
              items:
                type: string
                enum:
                - increasing
                - decreasing
                - none
                - forecast
            rows:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            secondaryRows:
              type: array
              description: Secondary time range rows.
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            forecastRows:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/Value'
            cacheHit:
              type: boolean
              description: If true, results were fetched from the cache.
  parameters:
    pageToken:
      name: pageToken
      in: query
      description: Page token, returned by a previous call, to request the next page of results
      schema:
        type: string
    maxResults:
      name: maxResults
      in: query
      description: The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection.
      schema:
        type: integer
        format: int64
        default: 50
    reportId:
      name: id
      in: path
      description: Report ID. See [Resource IDs](https://developer.doit.com/docs/resource-ids).
      required: true
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Tenant (customer) ID that sets the request''s customer context.


        Required when the credential can access more than one tenant; omit when the

        credential is scoped to exactly one tenant (the server resolves that tenant

        automatically). If omitted for a multi-tenant credential, the request fails

        with `400` and code `tenant_id_required`. If the value conflicts with the

        credential''s tenant scope, the request fails with `400` and code

        `tenant_id_mismatch`.


        Use this header over the legacy `customerContext` query parameter, which

        only applies to legacy API keys and is ignored by personal and service-account

        API tokens.

        '
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli