> ## 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. # Preview a report widget ## OpenAPI ````yaml POST /report-previews/widgets openapi: 3.0.0 info: title: Costory version: '1.0' description: API Documentation servers: - url: https://app-api.costory.io security: [] paths: /report-previews/widgets: post: tags: - Reports summary: Preview a report widget operationId: previewReportWidget requestBody: content: application/json: schema: type: object properties: 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_14_WEEKS - MTD - QTD - YTD - 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 - null default: {} widget: 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 description: Number of largest-increase rows to include. flopN: type: integer minimum: 0 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. 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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. 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: anyOf: - type: number enum: - 5 - type: number enum: - 10 - type: number enum: - 15 - type: number enum: - 20 - type: number enum: - 30 - type: number enum: - 50 default: 10 description: >- How many of the largest-absolute-change nodes to surface (5, 10, 15 or 20). 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. 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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 description: >- One report widget. The `type` field selects the shape: TOP_FLOP | GRAPH_SNAPSHOT | DASHBOARD_PDF | DIGEST | TEXT. All fields other than `type` depend on the chosen type. discriminator: propertyName: type required: - widget responses: '200': description: Widget preview result content: application/json: schema: $ref: '#/components/schemas/ReportWidgetPreview' '400': description: Invalid preview input content: application/json: schema: $ref: '#/components/schemas/ReportsValidationError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' security: - bearerAuth: [] components: schemas: ReportWidgetPreview: type: object properties: type: type: string enum: - TOP_FLOP - GRAPH_SNAPSHOT - DASHBOARD_PDF - DIGEST - TEXT status: type: string enum: - PENDING - SUCCESS - FAILED resolvedParameters: 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 description: Number of largest-increase rows to include. flopN: type: integer minimum: 0 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. 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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. 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: anyOf: - type: number enum: - 5 - type: number enum: - 10 - type: number enum: - 15 - type: number enum: - 20 - type: number enum: - 30 - type: number enum: - 50 default: 10 description: >- How many of the largest-absolute-change nodes to surface (5, 10, 15 or 20). 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. 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_14_WEEKS - MTD - QTD - YTD - 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 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 name: type: string 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 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 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 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 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 name: type: string 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 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 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 integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). metricName: type: string minLength: 1 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 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 required: - type - provider - integrationId - metricName - aggregator - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object properties: githubSourceRepos: type: array items: type: string default: [] enableAllGithubRepos: type: boolean customBusinessEvents: type: boolean default: true customTechnicalEvents: type: boolean default: true labels: type: array items: type: string default: [] commitments: type: boolean default: false reservations: type: boolean default: false marketplacePurchases: type: boolean default: false skuPriceChanges: type: boolean default: false sources: type: array items: type: string enum: - custom - provider - github - api bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 required: - period - queries - eventsFilter - 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 description: >- One report widget. The `type` field selects the shape: TOP_FLOP | GRAPH_SNAPSHOT | DASHBOARD_PDF | DIGEST | TEXT. All fields other than `type` depend on the chosen type. discriminator: propertyName: type result: oneOf: - type: object properties: type: type: string enum: - TOP_FLOP comparisonPeriodSummary: type: string top: type: array items: type: object properties: name: type: string value: type: number variation: type: number difference: type: number required: - name - value - variation additionalProperties: false flop: type: array items: type: object properties: name: type: string value: type: number variation: type: number difference: type: number required: - name - value - variation additionalProperties: false explorerUrl: type: string required: - type - top - flop additionalProperties: false - type: object properties: type: type: string enum: - GRAPH_SNAPSHOT imageUrl: type: string data: type: object properties: outputData: type: array items: type: object properties: date: type: string nullable: true format: date-time values: type: array items: type: object properties: groupByValue: type: string queryName: type: string value: type: number required: - groupByValue - queryName - value required: - date - values series: type: array items: type: object properties: queryName: type: string groupByValue: type: string totals: type: number unit: type: string required: - queryName - groupByValue - totals - unit aggBy: type: string enum: - Hour - Day - Week - Month - Period required: - outputData - series - aggBy explorerUrl: type: string required: - type - imageUrl - data additionalProperties: false - type: object properties: type: type: string enum: - DASHBOARD_PDF pdfUrl: type: string minLength: 1 required: - type - pdfUrl additionalProperties: false - type: object properties: type: type: string enum: - DIGEST comparisonPeriodSummary: type: string tree: type: array items: $ref: '#/components/schemas/DigestCostTreeNode' summaryMarkdown: type: string explorerUrl: type: string investigations: type: object additionalProperties: oneOf: - type: object properties: status: type: string enum: - PENDING required: - status - type: object properties: status: type: string enum: - SUCCESS output: type: object properties: summary: type: string methodology: type: string required: - summary required: - status - output - type: object properties: status: type: string enum: - FAILED error: type: object properties: message: type: string code: type: string tags: type: array items: type: string required: - status required: - type - tree additionalProperties: false - type: object properties: type: type: string enum: - TEXT contentMarkdown: type: string minLength: 1 maxLength: 10000 required: - type - contentMarkdown additionalProperties: false - nullable: true type: string enum: - null errorMessage: type: string nullable: true required: - type - status - resolvedParameters 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 DigestCostTreeNode: type: object properties: childs: type: array items: $ref: '#/components/schemas/DigestCostTreeNode' label: type: string previousCost: type: number cost: type: number key: type: string value: type: string childrenDimensionLabel: type: string nodeId: type: string required: - childs - label - previousCost - cost securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT or Clerk ak_* API key description: >- Send `Authorization: Bearer ` 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. ````