> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a test report delivery



## OpenAPI

````yaml https://app-api.costory.io/docs/openapi.json post /report-previews/deliveries
openapi: 3.0.0
info:
  title: Costory
  version: '1.0'
  description: API Documentation
servers:
  - url: ''
    description: Production server
security: []
paths:
  /report-previews/deliveries:
    post:
      tags:
        - Reports
      summary: Send a test report delivery
      operationId: sendTestReport
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    Report name. May be empty or whitespace — the server then
                    generates one from the report's content.
                description:
                  type: string
                  default: ''
                  description: Optional longer description (default empty).
                type:
                  type: string
                  enum:
                    - PRIVATE
                    - PUBLIC
                  default: PRIVATE
                  description: >-
                    Deprecated. On create, PUBLIC still seeds an organization
                    Editor grant (and PRIVATE does not). On update it is ignored
                    — grant Reader or Editor via PUT /access/report/:id/grants
                    instead. TEMPLATE is dashboard-only.
                tagIds:
                  type: array
                  items:
                    type: string
                  description: Existing org tag ids to assign. Omit for untagged.
                teamId:
                  type: string
                  nullable: true
                  description: >-
                    Deprecated. On create, a non-null teamId still seeds a team
                    Editor grant. On update it is ignored — grant a team Reader
                    or Editor via PUT /access/report/:id/grants instead.
                scout:
                  type: string
                  nullable: true
                  minLength: 1
                scopeId:
                  type: string
                  nullable: true
                context:
                  type: object
                  properties:
                    metricId:
                      type: string
                      nullable: true
                    groupBy:
                      type: string
                      nullable: true
                    datePreset:
                      type: string
                      nullable: true
                      enum:
                        - TRAILING_90_DAYS
                        - TRAILING_30_DAYS
                        - TRAILING_45_DAYS
                        - TRAILING_7_DAYS
                        - TRAILING_3_DAYS
                        - TRAILING_1_DAYS
                        - TRAILING_14_WEEKS
                        - MTD
                        - QTD
                        - YTD
                        - CURRENT_MONTH
                        - CURRENT_QUARTER
                        - CURRENT_YEAR
                        - LAST_WEEK
                        - LAST_MONTH
                        - LAST_6_MONTHS
                        - LAST_12_MONTHS
                        - LAST_4_YEARS
                        - LAST_3_MONTHS
                        - LAST_INVOICE_MONTH
                        - null
                    startDate:
                      type: string
                      nullable: true
                    endDate:
                      type: string
                      nullable: true
                    conditions:
                      type: object
                      nullable: true
                      properties: {}
                      additionalProperties: {}
                    currency:
                      type: string
                      nullable: true
                      enum:
                        - USD
                        - EUR
                        - GBP
                        - CNY
                        - KRW
                        - null
                  default: {}
                  description: >-
                    Report-wide defaults (metric, group-by, date range, filters,
                    currency) that widgets and destinations inherit unless they
                    override them.
                scheduledPeriod:
                  type: string
                  nullable: true
                  enum:
                    - DAILY
                    - WEEKDAYS
                    - WEEKLY
                    - MONTHLY
                    - null
                  description: >-
                    Delivery cadence, or null for an on-demand (one-time) report
                    that only runs when triggered.
                scheduledWeekday:
                  type: number
                  description: >-
                    Day of week for WEEKLY reports: 0 = Sunday … 6 = Saturday.
                    Required when `scheduledPeriod` is WEEKLY; ignored for every
                    other cadence.
                scheduledFirstRunAt:
                  type: string
                  nullable: true
                  format: date-time
                  description: >-
                    First send date (UTC). The time of day is ignored: the
                    report is due for the whole UTC day, as soon as the org is
                    ready. Ignored once the report has run at least once.
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                widgets:
                  type: array
                  items:
                    allOf:
                      - type: object
                        properties:
                          id:
                            type: string
                            format: cuid
                          title:
                            type: string
                            default: ''
                          description:
                            type: string
                            default: ''
                      - oneOf:
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - TOP_FLOP
                                description: >-
                                  Ranked table of the biggest cost increases and
                                  decreases.
                              topN:
                                type: integer
                                minimum: 0
                                maximum: 100
                                description: Number of largest-increase rows to include.
                              flopN:
                                type: integer
                                minimum: 0
                                maximum: 100
                                description: Number of largest-decrease rows to include.
                              cutOff:
                                type: number
                                minimum: 0
                                default: 10
                                description: >-
                                  Minimum absolute cost change for a row to
                                  qualify. Rows below this are dropped.
                              comparison:
                                oneOf:
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                          - PREVIOUS_PERIOD
                                    required:
                                      - kind
                                    additionalProperties: false
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                          - CUSTOM
                                      from:
                                        type: string
                                        minLength: 1
                                      to:
                                        type: string
                                        minLength: 1
                                    required:
                                      - kind
                                      - from
                                      - to
                                default:
                                  kind: PREVIOUS_PERIOD
                                description: >-
                                  Baseline the current period is compared
                                  against: PREVIOUS_PERIOD (default) or a CUSTOM
                                  { from, to } range.
                                discriminator:
                                  propertyName: kind
                              advancedExplorerRequest:
                                type: object
                                properties:
                                  period:
                                    type: object
                                    properties:
                                      startDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      endDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      datePreset:
                                        type: string
                                        nullable: true
                                        enum:
                                          - TRAILING_90_DAYS
                                          - TRAILING_30_DAYS
                                          - TRAILING_45_DAYS
                                          - TRAILING_7_DAYS
                                          - TRAILING_3_DAYS
                                          - TRAILING_1_DAYS
                                          - TRAILING_14_WEEKS
                                          - MTD
                                          - QTD
                                          - YTD
                                          - CURRENT_MONTH
                                          - CURRENT_QUARTER
                                          - CURRENT_YEAR
                                          - LAST_WEEK
                                          - LAST_MONTH
                                          - LAST_6_MONTHS
                                          - LAST_12_MONTHS
                                          - LAST_4_YEARS
                                          - LAST_3_MONTHS
                                          - LAST_INVOICE_MONTH
                                          - null
                                      aggBy:
                                        type: string
                                        enum:
                                          - Hour
                                          - Day
                                          - Week
                                          - Month
                                          - Period
                                      forecastDays:
                                        type: integer
                                        minimum: 0
                                      comparisonPeriod:
                                        type: object
                                        properties:
                                          startDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          endDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          enabled:
                                            type: boolean
                                          chartType:
                                            type: string
                                            enum:
                                              - WATERFALL
                                              - TABLE
                                              - KPI_BREAKDOWN
                                        required:
                                          - startDate
                                          - endDate
                                          - enabled
                                          - chartType
                                    required:
                                      - aggBy
                                  queries:
                                    type: array
                                    items:
                                      oneOf:
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - condition
                                            expression:
                                              type: string
                                              minLength: 1
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                          required:
                                            - type
                                            - expression
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - formula
                                            formula:
                                              type: string
                                            unitOverride:
                                              type: string
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - formula
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - metric
                                            metricId:
                                              type: string
                                            rawMetric:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            unitOverride:
                                              type: string
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - metricId
                                            - aggregator
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - cost
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            currency:
                                              type: string
                                              enum:
                                                - USD
                                                - EUR
                                                - GBP
                                                - CNY
                                                - KRW
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            metricId:
                                              type: string
                                              enum:
                                                - cost
                                                - effective_cost
                                                - list_cost
                                                - contracted_cost
                                                - unblended_cost
                                                - net_unblended_cost
                                                - amortized_cost
                                                - net_amortized_cost
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - aggregator
                                            - whereClause
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - usage
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            metricId:
                                              type: string
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - whereClause
                                            - aggregator
                                            - metricId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - budget
                                            budgetId:
                                              type: string
                                            budgetLineId:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            virtualDimensionValue:
                                              type: string
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                              default: SUM
                                          required:
                                            - type
                                            - budgetId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - externalMetric
                                            provider:
                                              type: string
                                              enum:
                                                - tsuga
                                                - bigquery
                                                - datadog
                                                - cloudwatch
                                                - s3
                                                - amplitude
                                                - snowflake
                                                - cloudmonitoring
                                                - push
                                            integrationId:
                                              type: string
                                              minLength: 1
                                              description: >-
                                                External metric integration ID from
                                                list_metrics(includeExternal: true).
                                            query:
                                              type: string
                                              minLength: 1
                                            metricName:
                                              type: string
                                              default: ''
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupByFields:
                                              type: array
                                              items:
                                                type: string
                                                minLength: 1
                                              maxItems: 7
                                              default: []
                                            conditions:
                                              type: string
                                            dateColumn:
                                              type: string
                                              minLength: 1
                                            metricColumn:
                                              type: string
                                              minLength: 1
                                            gapFillingMethod:
                                              type: string
                                              enum:
                                                - ZERO
                                                - FORWARD_FILL
                                                - LINEAR_INTERPOLATION
                                                - SPREAD
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            unitOverride:
                                              type: string
                                          required:
                                            - type
                                            - provider
                                            - integrationId
                                            - name
                                            - colorIndex
                                            - chartType
                                      discriminator:
                                        propertyName: type
                                  eventsFilter:
                                    type: object
                                    nullable: true
                                    properties:
                                      sources:
                                        type: array
                                        items:
                                          type: string
                                          enum:
                                            - custom
                                            - provider
                                            - github
                                            - api
                                            - agent
                                        default:
                                          - custom
                                          - api
                                      githubSourceRepos:
                                        type: array
                                        items:
                                          type: string
                                        default: []
                                      search:
                                        type: string
                                        default: ''
                                  bookmarkedEvents:
                                    type: array
                                    items:
                                      type: string
                                  scopeId:
                                    type: string
                                    nullable: true
                                  limitOverride:
                                    type: integer
                                    minimum: 1
                                    maximum: 1000
                                  displayOptions:
                                    type: object
                                    properties:
                                      sort:
                                        type: object
                                        properties:
                                          by:
                                            type: string
                                            minLength: 1
                                          direction:
                                            type: string
                                            enum:
                                              - ASC
                                              - DESC
                                            default: DESC
                                        required:
                                          - by
                                      hideEmptyRows:
                                        type: boolean
                                      topN:
                                        type: integer
                                        minimum: 1
                                        maximum: 100
                                      showTotal:
                                        type: boolean
                                      precision:
                                        type: integer
                                        minimum: 0
                                        maximum: 6
                                      pivot:
                                        type: object
                                        properties:
                                          rows:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                          columns:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                        required:
                                          - rows
                                          - columns
                                        additionalProperties: false
                                    additionalProperties: false
                                required:
                                  - period
                                  - queries
                                  - bookmarkedEvents
                                description: >-
                                  Advanced Explorer query that defines this
                                  widget's data set: metric, group-by, period,
                                  filters and scope. Same shape as the Explorer
                                  API.
                            required:
                              - type
                              - topN
                              - flopN
                              - advancedExplorerRequest
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - GRAPH_SNAPSHOT
                                description: >-
                                  Rendered snapshot of an Advanced Explorer
                                  chart.
                              advancedExplorerRequest:
                                type: object
                                properties:
                                  period:
                                    type: object
                                    properties:
                                      startDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      endDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      datePreset:
                                        type: string
                                        nullable: true
                                        enum:
                                          - TRAILING_90_DAYS
                                          - TRAILING_30_DAYS
                                          - TRAILING_45_DAYS
                                          - TRAILING_7_DAYS
                                          - TRAILING_3_DAYS
                                          - TRAILING_1_DAYS
                                          - TRAILING_14_WEEKS
                                          - MTD
                                          - QTD
                                          - YTD
                                          - CURRENT_MONTH
                                          - CURRENT_QUARTER
                                          - CURRENT_YEAR
                                          - LAST_WEEK
                                          - LAST_MONTH
                                          - LAST_6_MONTHS
                                          - LAST_12_MONTHS
                                          - LAST_4_YEARS
                                          - LAST_3_MONTHS
                                          - LAST_INVOICE_MONTH
                                          - null
                                      aggBy:
                                        type: string
                                        enum:
                                          - Hour
                                          - Day
                                          - Week
                                          - Month
                                          - Period
                                      forecastDays:
                                        type: integer
                                        minimum: 0
                                      comparisonPeriod:
                                        type: object
                                        properties:
                                          startDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          endDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          enabled:
                                            type: boolean
                                          chartType:
                                            type: string
                                            enum:
                                              - WATERFALL
                                              - TABLE
                                              - KPI_BREAKDOWN
                                        required:
                                          - startDate
                                          - endDate
                                          - enabled
                                          - chartType
                                    required:
                                      - aggBy
                                  queries:
                                    type: array
                                    items:
                                      oneOf:
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - condition
                                            expression:
                                              type: string
                                              minLength: 1
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                          required:
                                            - type
                                            - expression
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - formula
                                            formula:
                                              type: string
                                            unitOverride:
                                              type: string
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - formula
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - metric
                                            metricId:
                                              type: string
                                            rawMetric:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            unitOverride:
                                              type: string
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - metricId
                                            - aggregator
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - cost
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            currency:
                                              type: string
                                              enum:
                                                - USD
                                                - EUR
                                                - GBP
                                                - CNY
                                                - KRW
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            metricId:
                                              type: string
                                              enum:
                                                - cost
                                                - effective_cost
                                                - list_cost
                                                - contracted_cost
                                                - unblended_cost
                                                - net_unblended_cost
                                                - amortized_cost
                                                - net_amortized_cost
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - aggregator
                                            - whereClause
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - usage
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            metricId:
                                              type: string
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - whereClause
                                            - aggregator
                                            - metricId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - budget
                                            budgetId:
                                              type: string
                                            budgetLineId:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            virtualDimensionValue:
                                              type: string
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                              default: SUM
                                          required:
                                            - type
                                            - budgetId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - externalMetric
                                            provider:
                                              type: string
                                              enum:
                                                - tsuga
                                                - bigquery
                                                - datadog
                                                - cloudwatch
                                                - s3
                                                - amplitude
                                                - snowflake
                                                - cloudmonitoring
                                                - push
                                            integrationId:
                                              type: string
                                              minLength: 1
                                              description: >-
                                                External metric integration ID from
                                                list_metrics(includeExternal: true).
                                            query:
                                              type: string
                                              minLength: 1
                                            metricName:
                                              type: string
                                              default: ''
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupByFields:
                                              type: array
                                              items:
                                                type: string
                                                minLength: 1
                                              maxItems: 7
                                              default: []
                                            conditions:
                                              type: string
                                            dateColumn:
                                              type: string
                                              minLength: 1
                                            metricColumn:
                                              type: string
                                              minLength: 1
                                            gapFillingMethod:
                                              type: string
                                              enum:
                                                - ZERO
                                                - FORWARD_FILL
                                                - LINEAR_INTERPOLATION
                                                - SPREAD
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            unitOverride:
                                              type: string
                                          required:
                                            - type
                                            - provider
                                            - integrationId
                                            - name
                                            - colorIndex
                                            - chartType
                                      discriminator:
                                        propertyName: type
                                  eventsFilter:
                                    type: object
                                    nullable: true
                                    properties:
                                      sources:
                                        type: array
                                        items:
                                          type: string
                                          enum:
                                            - custom
                                            - provider
                                            - github
                                            - api
                                            - agent
                                        default:
                                          - custom
                                          - api
                                      githubSourceRepos:
                                        type: array
                                        items:
                                          type: string
                                        default: []
                                      search:
                                        type: string
                                        default: ''
                                  bookmarkedEvents:
                                    type: array
                                    items:
                                      type: string
                                  scopeId:
                                    type: string
                                    nullable: true
                                  limitOverride:
                                    type: integer
                                    minimum: 1
                                    maximum: 1000
                                  displayOptions:
                                    type: object
                                    properties:
                                      sort:
                                        type: object
                                        properties:
                                          by:
                                            type: string
                                            minLength: 1
                                          direction:
                                            type: string
                                            enum:
                                              - ASC
                                              - DESC
                                            default: DESC
                                        required:
                                          - by
                                      hideEmptyRows:
                                        type: boolean
                                      topN:
                                        type: integer
                                        minimum: 1
                                        maximum: 100
                                      showTotal:
                                        type: boolean
                                      precision:
                                        type: integer
                                        minimum: 0
                                        maximum: 6
                                      pivot:
                                        type: object
                                        properties:
                                          rows:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                          columns:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                        required:
                                          - rows
                                          - columns
                                        additionalProperties: false
                                    additionalProperties: false
                                required:
                                  - period
                                  - queries
                                  - bookmarkedEvents
                                description: >-
                                  Advanced Explorer query that defines this
                                  widget's data set: metric, group-by, period,
                                  filters and scope. Same shape as the Explorer
                                  API.
                            required:
                              - type
                              - advancedExplorerRequest
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - DASHBOARD_PDF
                                description: >-
                                  A dashboard rendered to PDF and attached to
                                  the report.
                              dashboardV2Id:
                                type: string
                                minLength: 1
                                description: Id of the dashboard to render as a PDF.
                              datePreset:
                                type: string
                                nullable: true
                                enum:
                                  - TRAILING_90_DAYS
                                  - TRAILING_30_DAYS
                                  - TRAILING_45_DAYS
                                  - TRAILING_7_DAYS
                                  - TRAILING_3_DAYS
                                  - TRAILING_1_DAYS
                                  - TRAILING_14_WEEKS
                                  - MTD
                                  - QTD
                                  - YTD
                                  - CURRENT_MONTH
                                  - CURRENT_QUARTER
                                  - CURRENT_YEAR
                                  - LAST_WEEK
                                  - LAST_MONTH
                                  - LAST_6_MONTHS
                                  - LAST_12_MONTHS
                                  - LAST_4_YEARS
                                  - LAST_3_MONTHS
                                  - LAST_INVOICE_MONTH
                                  - null
                                description: >-
                                  Optional period override for every dashboard
                                  widget in the PDF. Omit to inherit the report
                                  (and destination) period. Mutually exclusive
                                  with startDate/endDate.
                              startDate:
                                type: string
                                nullable: true
                                description: >-
                                  Optional custom range start (YYYY-MM-DD). Use
                                  with endDate instead of datePreset.
                              endDate:
                                type: string
                                nullable: true
                                description: >-
                                  Optional custom range end (inclusive,
                                  YYYY-MM-DD). Use with startDate instead of
                                  datePreset.
                            required:
                              - type
                              - dashboardV2Id
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - DIGEST
                                description: >-
                                  Cost-change breakdown as a tree, table, or LLM
                                  summary of the biggest movers.
                              display:
                                type: string
                                enum:
                                  - tree
                                  - table
                                  - summary
                                default: tree
                                description: >-
                                  How the digest renders: 'tree' (default
                                  hierarchy), flat 'table', or an LLM-written
                                  'summary'.
                              showValue:
                                type: boolean
                                default: true
                                description: Show the absolute cost value on each row.
                              showRelativeDelta:
                                type: boolean
                                default: true
                                description: Show the percentage change on each row.
                              showDelta:
                                type: boolean
                                default: true
                                description: Show the absolute change on each row.
                              topLargestAbsoluteChange:
                                type: integer
                                minimum: 1
                                maximum: 100
                                default: 10
                                description: >-
                                  How many of the largest-absolute-change nodes
                                  to surface (integer 1–100). Applied at every
                                  tree level.
                              minAbsoluteDiff:
                                type: number
                                minimum: 0
                                default: 100
                                description: >-
                                  Hide nodes whose absolute change is below this
                                  threshold.
                              minRelativeDiff:
                                type: number
                                minimum: 0
                                default: 5
                                description: >-
                                  Hide nodes whose percentage change is below
                                  this threshold (percent).
                              additionalGroupBy:
                                type: array
                                items:
                                  type: string
                                  minLength: 1
                                default: []
                                description: >-
                                  Extra group-by dimensions applied after the
                                  report context `groupBy`, in order — each adds
                                  a deeper level to the tree.
                              useDashboardGroupBy:
                                type: boolean
                                description: >-
                                  Use the report (dashboard) context `groupBy`
                                  as this widget's root group-by (default true).
                                  Set false to override: the report context
                                  group-by is ignored for this widget and the
                                  first `additionalGroupBy` item (or the widget
                                  cost query `groupBy`) becomes the root.
                                  `false` requires at least one group-by
                                  dimension.
                              enableAiInvestigation:
                                type: boolean
                                default: false
                                description: >-
                                  When true, the run's deepest-leaf nodes
                                  trigger an async AI investigation
                                  (`analysis_agent_run`) and the report waits
                                  for its callback before sending. Delivery is
                                  not immediate.
                              advancedExplorerRequest:
                                type: object
                                properties:
                                  period:
                                    type: object
                                    properties:
                                      startDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      endDate:
                                        type: string
                                        nullable: true
                                        format: date-time
                                      datePreset:
                                        type: string
                                        nullable: true
                                        enum:
                                          - TRAILING_90_DAYS
                                          - TRAILING_30_DAYS
                                          - TRAILING_45_DAYS
                                          - TRAILING_7_DAYS
                                          - TRAILING_3_DAYS
                                          - TRAILING_1_DAYS
                                          - TRAILING_14_WEEKS
                                          - MTD
                                          - QTD
                                          - YTD
                                          - CURRENT_MONTH
                                          - CURRENT_QUARTER
                                          - CURRENT_YEAR
                                          - LAST_WEEK
                                          - LAST_MONTH
                                          - LAST_6_MONTHS
                                          - LAST_12_MONTHS
                                          - LAST_4_YEARS
                                          - LAST_3_MONTHS
                                          - LAST_INVOICE_MONTH
                                          - null
                                      aggBy:
                                        type: string
                                        enum:
                                          - Hour
                                          - Day
                                          - Week
                                          - Month
                                          - Period
                                      forecastDays:
                                        type: integer
                                        minimum: 0
                                      comparisonPeriod:
                                        type: object
                                        properties:
                                          startDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          endDate:
                                            type: string
                                            nullable: true
                                            format: date-time
                                          enabled:
                                            type: boolean
                                          chartType:
                                            type: string
                                            enum:
                                              - WATERFALL
                                              - TABLE
                                              - KPI_BREAKDOWN
                                        required:
                                          - startDate
                                          - endDate
                                          - enabled
                                          - chartType
                                    required:
                                      - aggBy
                                  queries:
                                    type: array
                                    items:
                                      oneOf:
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - condition
                                            expression:
                                              type: string
                                              minLength: 1
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                          required:
                                            - type
                                            - expression
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - formula
                                            formula:
                                              type: string
                                            unitOverride:
                                              type: string
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - formula
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - metric
                                            metricId:
                                              type: string
                                            rawMetric:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            unitOverride:
                                              type: string
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - metricId
                                            - aggregator
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - cost
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            currency:
                                              type: string
                                              enum:
                                                - USD
                                                - EUR
                                                - GBP
                                                - CNY
                                                - KRW
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            metricId:
                                              type: string
                                              enum:
                                                - cost
                                                - effective_cost
                                                - list_cost
                                                - contracted_cost
                                                - unblended_cost
                                                - net_unblended_cost
                                                - amortized_cost
                                                - net_amortized_cost
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - aggregator
                                            - whereClause
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - usage
                                            whereClause:
                                              type: object
                                              properties: {}
                                              additionalProperties: {}
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            metricId:
                                              type: string
                                            extendDashboardConditions:
                                              type: boolean
                                              default: true
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            reducer:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            excludeGroupByValue:
                                              type: object
                                              properties:
                                                source:
                                                  type: object
                                                  properties:
                                                    type:
                                                      type: string
                                                      enum:
                                                        - indexation
                                                  required:
                                                    - type
                                                  additionalProperties: false
                                              required:
                                                - source
                                              additionalProperties: false
                                              description: >-
                                                Exclude group-by values already present
                                                in the billing-stats indexation catalog
                                                before the query window. HTTP API only;
                                                not available on MCP query.
                                            shiftAmount:
                                              type: integer
                                            shiftUnit:
                                              type: string
                                              enum:
                                                - DAY
                                                - WEEK
                                                - MONTH
                                          required:
                                            - type
                                            - whereClause
                                            - aggregator
                                            - metricId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - budget
                                            budgetId:
                                              type: string
                                            budgetLineId:
                                              type: string
                                            groupBy:
                                              anyOf:
                                                - type: string
                                                - type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                - nullable: true
                                                  type: string
                                                  enum:
                                                    - null
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            virtualDimensionValue:
                                              type: string
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                              default: SUM
                                          required:
                                            - type
                                            - budgetId
                                            - name
                                            - colorIndex
                                            - chartType
                                        - type: object
                                          properties:
                                            type:
                                              type: string
                                              enum:
                                                - externalMetric
                                            provider:
                                              type: string
                                              enum:
                                                - tsuga
                                                - bigquery
                                                - datadog
                                                - cloudwatch
                                                - s3
                                                - amplitude
                                                - snowflake
                                                - cloudmonitoring
                                                - push
                                            integrationId:
                                              type: string
                                              minLength: 1
                                              description: >-
                                                External metric integration ID from
                                                list_metrics(includeExternal: true).
                                            query:
                                              type: string
                                              minLength: 1
                                            metricName:
                                              type: string
                                              default: ''
                                            aggregator:
                                              type: string
                                              enum:
                                                - SUM
                                                - AVG
                                                - MAX
                                                - MIN
                                            groupByFields:
                                              type: array
                                              items:
                                                type: string
                                                minLength: 1
                                              maxItems: 7
                                              default: []
                                            conditions:
                                              type: string
                                            dateColumn:
                                              type: string
                                              minLength: 1
                                            metricColumn:
                                              type: string
                                              minLength: 1
                                            gapFillingMethod:
                                              type: string
                                              enum:
                                                - ZERO
                                                - FORWARD_FILL
                                                - LINEAR_INTERPOLATION
                                                - SPREAD
                                            name:
                                              type: string
                                              pattern: ^[A-Za-z_][A-Za-z0-9_]*$
                                            alias:
                                              type: string
                                              minLength: 1
                                              maxLength: 50
                                            visible:
                                              type: boolean
                                              default: true
                                            colorIndex:
                                              type: number
                                            chartType:
                                              type: string
                                              enum:
                                                - BAR
                                                - LINE
                                                - AREA
                                                - WATERFALL
                                                - TABLE
                                            colorPalette:
                                              type: string
                                              enum:
                                                - DEFAULT
                                                - PIYG
                                                - RDYLBU
                                                - CLASSIC
                                              default: DEFAULT
                                            rollingAggregation:
                                              type: object
                                              properties:
                                                aggregator:
                                                  type: string
                                                  enum:
                                                    - SUM
                                                    - AVG
                                                    - MAX
                                                    - MIN
                                                window:
                                                  type: object
                                                  properties:
                                                    preset:
                                                      type: string
                                                      enum:
                                                        - MONTH
                                                        - WEEK
                                                    relativeDays:
                                                      type: integer
                                                      minimum: 1
                                              required:
                                                - aggregator
                                                - window
                                            unitOverride:
                                              type: string
                                          required:
                                            - type
                                            - provider
                                            - integrationId
                                            - name
                                            - colorIndex
                                            - chartType
                                      discriminator:
                                        propertyName: type
                                  eventsFilter:
                                    type: object
                                    nullable: true
                                    properties:
                                      sources:
                                        type: array
                                        items:
                                          type: string
                                          enum:
                                            - custom
                                            - provider
                                            - github
                                            - api
                                            - agent
                                        default:
                                          - custom
                                          - api
                                      githubSourceRepos:
                                        type: array
                                        items:
                                          type: string
                                        default: []
                                      search:
                                        type: string
                                        default: ''
                                  bookmarkedEvents:
                                    type: array
                                    items:
                                      type: string
                                  scopeId:
                                    type: string
                                    nullable: true
                                  limitOverride:
                                    type: integer
                                    minimum: 1
                                    maximum: 1000
                                  displayOptions:
                                    type: object
                                    properties:
                                      sort:
                                        type: object
                                        properties:
                                          by:
                                            type: string
                                            minLength: 1
                                          direction:
                                            type: string
                                            enum:
                                              - ASC
                                              - DESC
                                            default: DESC
                                        required:
                                          - by
                                      hideEmptyRows:
                                        type: boolean
                                      topN:
                                        type: integer
                                        minimum: 1
                                        maximum: 100
                                      showTotal:
                                        type: boolean
                                      precision:
                                        type: integer
                                        minimum: 0
                                        maximum: 6
                                      pivot:
                                        type: object
                                        properties:
                                          rows:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                          columns:
                                            type: array
                                            items:
                                              type: string
                                              enum:
                                                - groupBy
                                                - query
                                                - time
                                            minItems: 1
                                        required:
                                          - rows
                                          - columns
                                        additionalProperties: false
                                    additionalProperties: false
                                required:
                                  - period
                                  - queries
                                  - bookmarkedEvents
                                description: >-
                                  Advanced Explorer query that defines this
                                  widget's data set: metric, group-by, period,
                                  filters and scope. Same shape as the Explorer
                                  API.
                            required:
                              - type
                              - advancedExplorerRequest
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - TEXT
                                description: >-
                                  Free-form Markdown block (headings, notes,
                                  context).
                              contentMarkdown:
                                type: string
                                minLength: 1
                                maxLength: 10000
                                description: Markdown content, 1–10,000 characters.
                            required:
                              - type
                              - contentMarkdown
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - DIVIDER
                                description: >-
                                  Slack thread cut: widgets above post in the
                                  channel, widgets below post as replies.
                                  Ignored for email and Teams. At most one per
                                  report.
                            required:
                              - type
                        description: >-
                          One report widget. The `type` field selects the shape:
                          TOP_FLOP | GRAPH_SNAPSHOT | DASHBOARD_PDF | DIGEST |
                          TEXT | DIVIDER. All fields other than `type` depend on
                          the chosen type.
                        discriminator:
                          propertyName: type
                  default: []
                  description: >-
                    Ordered widgets that make up the report body. Each widget's
                    `type` selects its shape (see ReportWidgetParameters).
                destinations:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: cuid
                      metricId:
                        type: string
                        nullable: true
                      groupBy:
                        type: string
                        nullable: true
                      datePreset:
                        type: string
                        nullable: true
                        enum:
                          - TRAILING_90_DAYS
                          - TRAILING_30_DAYS
                          - TRAILING_45_DAYS
                          - TRAILING_7_DAYS
                          - TRAILING_3_DAYS
                          - TRAILING_1_DAYS
                          - TRAILING_14_WEEKS
                          - MTD
                          - QTD
                          - YTD
                          - CURRENT_MONTH
                          - CURRENT_QUARTER
                          - CURRENT_YEAR
                          - LAST_WEEK
                          - LAST_MONTH
                          - LAST_6_MONTHS
                          - LAST_12_MONTHS
                          - LAST_4_YEARS
                          - LAST_3_MONTHS
                          - LAST_INVOICE_MONTH
                          - null
                      startDate:
                        type: string
                        nullable: true
                      endDate:
                        type: string
                        nullable: true
                      conditions:
                        type: object
                        nullable: true
                        properties: {}
                        additionalProperties: {}
                      currency:
                        type: string
                        nullable: true
                        enum:
                          - USD
                          - EUR
                          - GBP
                          - CNY
                          - KRW
                          - null
                      scopeId:
                        type: string
                        nullable: true
                      destinationType:
                        type: string
                        enum:
                          - SLACK
                          - EMAIL
                          - TEAMS
                        description: 'Delivery channel: EMAIL, SLACK, or TEAMS.'
                      destinationValues:
                        type: array
                        items:
                          type: string
                          minLength: 1
                        minItems: 1
                        maxItems: 20
                        description: >-
                          One or more delivery targets sharing this
                          destination's filters/context. EMAIL: addresses or
                          ALL_ACTIVE_USERS; SLACK: channel ids; TEAMS: channel
                          ids.
                    required:
                      - destinationType
                      - destinationValues
                  minItems: 1
                  description: >-
                    Delivery targets. At least one is required. Each report is
                    fanned out to every destination on every run.
                reportId:
                  type: string
                  format: cuid
              required:
                - name
                - scheduledPeriod
                - destinations
            example:
              name: Weekly cloud cost digest
              description: Top movers across our AWS + GCP spend
              type: PRIVATE
              context:
                metricId: cost
                groupBy: provider
                datePreset: TRAILING_90_DAYS
                currency: USD
              scheduledPeriod: WEEKLY
              scheduledWeekday: 1
              status: ACTIVE
              widgets:
                - type: TEXT
                  contentMarkdown: '## Weekly summary'
              destinations:
                - destinationType: SLACK
                  destinationValues:
                    - C0123456789
                - destinationType: EMAIL
                  destinationValues:
                    - finance@acme.com
      responses:
        '200':
          description: Per-destination send results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsTestSendOutput'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ReportsForbidden'
                  - $ref: '#/components/schemas/ReportsTeamMemberRequired'
        '404':
          description: Team scope or related resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsNotFound'
      security:
        - bearerAuth: []
components:
  schemas:
    ReportsTestSendOutput:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              destinationIndex:
                type: integer
                minimum: 0
              ok:
                type: boolean
              errorMessage:
                type: string
                nullable: true
            required:
              - destinationIndex
              - ok
            additionalProperties: false
      required:
        - results
      additionalProperties: false
    ReportsValidationError:
      type: object
      properties:
        error:
          type: string
          enum:
            - VALIDATION_ERROR
        reason:
          type: string
        details:
          anyOf:
            - type: string
            - type: number
            - type: boolean
            - nullable: true
              type: string
              enum:
                - null
            - type: array
              items: {}
            - type: object
              additionalProperties: {}
      required:
        - error
        - details
      additionalProperties: false
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          description: Unauthorized error message
      required:
        - error
    ReportsForbidden:
      type: object
      properties:
        error:
          type: string
          enum:
            - FORBIDDEN
      required:
        - error
      additionalProperties: false
    ReportsTeamMemberRequired:
      type: object
      properties:
        error:
          type: string
          enum:
            - TEAM_MEMBER_REQUIRED
      required:
        - error
      additionalProperties: false
    ReportsNotFound:
      type: object
      properties:
        error:
          type: string
          enum:
            - NOT_FOUND
        reason:
          type: string
      required:
        - error
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or Clerk ak_* API key
      description: >-
        Send `Authorization: Bearer <credential>` using either a Clerk session
        JWT or a Clerk API key (`ak_*`). API keys may identify a user (`user_*`)
        or organization (`org_*`) principal and are generated in the Clerk
        Dashboard under API keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.