> ## 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. # Update a report > Partially updates a report; omitted fields are left unchanged. `widgets` and `destinations`, when provided, replace the existing lists wholesale. Same conditional rules as create apply: a WEEKLY cadence needs a `scheduledWeekday` (from this body or already stored), EMAIL destinations must be valid addresses, and a `table` DIGEST widget allows at most two group-by dimensions. Archived reports cannot be updated (409). ## OpenAPI ````yaml PATCH /reports/{id} openapi: 3.0.0 info: title: Costory version: '1.0' description: API Documentation servers: - url: https://app-api.costory.io security: [] paths: /reports/{id}: patch: tags: - Reports summary: Update a report description: >- Partially updates a report; omitted fields are left unchanged. `widgets` and `destinations`, when provided, replace the existing lists wholesale. Same conditional rules as create apply: a WEEKLY cadence needs a `scheduledWeekday` (from this body or already stored), EMAIL destinations must be valid addresses, and a `table` DIGEST widget allows at most two group-by dimensions. Archived reports cannot be updated (409). operationId: updateReport parameters: - schema: type: string format: cuid required: true name: id in: path requestBody: content: application/json: schema: type: object properties: name: type: string description: Optional name patch. description: type: string description: Optional description patch. type: type: string enum: - PRIVATE - PUBLIC - TEMPLATE teamId: type: string nullable: true 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_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 scheduledPeriod: type: string nullable: true enum: - DAILY - WEEKDAYS - WEEKLY - MONTHLY - null description: >- Delivery cadence, or null for an on-demand report. Switching to WEEKLY requires a `scheduledWeekday` (in this body or already stored). scheduledWeekday: type: number description: >- Day of week for WEEKLY reports: 0 = Sunday … 6 = Saturday. Only validated when present in the body. scheduledFirstRunAt: type: string nullable: true format: date-time 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 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 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_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 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 archivedAt: type: string nullable: true format: date-time 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: '204': description: Report updated '400': description: Validation or scope error content: application/json: schema: anyOf: - $ref: '#/components/schemas/ReportsValidationError' - type: object properties: error: type: string enum: - SCOPE_NOT_FOUND required: - error additionalProperties: false - type: object properties: error: type: string enum: - DESTINATIONS_REQUIRED required: - error additionalProperties: false '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' '409': description: Archived report cannot be updated content: application/json: schema: type: object properties: error: type: string enum: - REPORT_ARCHIVED required: - error additionalProperties: false security: - bearerAuth: [] components: schemas: 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 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. ````