DoiT Reports API

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

# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/doit/refs/heads/main/openapi/doit-reports-api-openapi.yml