> ## 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. # Create a dashboard > Creates a DashboardV2 from a bulk-save payload (metadata + widgets with explicit grid positions). Team/scope assignment is validated against membership. ## OpenAPI ````yaml https://app-api.costory.io/docs/openapi.json post /dashboard-v2 openapi: 3.0.0 info: title: Costory version: '1.0' description: API Documentation servers: - url: '' description: Production server security: [] paths: /dashboard-v2: post: tags: - Dashboards summary: Create a dashboard description: >- Creates a DashboardV2 from a bulk-save payload (metadata + widgets with explicit grid positions). Team/scope assignment is validated against membership. operationId: createDashboard requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string default: '' type: type: string enum: - PRIVATE - PUBLIC - TEMPLATE teamId: type: string nullable: true scopeId: type: string nullable: true metricId: type: string nullable: true groupBy: type: string nullable: true datePreset: type: string nullable: true enum: - TRAILING_90_DAYS - TRAILING_30_DAYS - TRAILING_45_DAYS - TRAILING_7_DAYS - TRAILING_3_DAYS - TRAILING_1_DAYS - TRAILING_14_WEEKS - MTD - QTD - YTD - CURRENT_MONTH - CURRENT_QUARTER - CURRENT_YEAR - LAST_WEEK - LAST_MONTH - LAST_6_MONTHS - LAST_12_MONTHS - LAST_4_YEARS - LAST_3_MONTHS - LAST_INVOICE_MONTH - null startDate: type: string nullable: true endDate: type: string nullable: true conditions: type: object nullable: true properties: {} additionalProperties: {} currency: type: string nullable: true enum: - USD - EUR - GBP - CNY - KRW - null widgets: type: array items: type: object properties: key: type: string x: type: number 'y': type: number w: type: number h: type: number title: type: string description: type: string default: '' source: oneOf: - type: object properties: type: type: string enum: - advancedExplorer request: type: object properties: period: type: object properties: startDate: type: string nullable: true format: date-time endDate: type: string nullable: true format: date-time datePreset: type: string nullable: true enum: - TRAILING_90_DAYS - TRAILING_30_DAYS - TRAILING_45_DAYS - TRAILING_7_DAYS - TRAILING_3_DAYS - TRAILING_1_DAYS - TRAILING_14_WEEKS - MTD - QTD - YTD - CURRENT_MONTH - CURRENT_QUARTER - CURRENT_YEAR - LAST_WEEK - LAST_MONTH - LAST_6_MONTHS - LAST_12_MONTHS - LAST_4_YEARS - LAST_3_MONTHS - LAST_INVOICE_MONTH - null aggBy: type: string enum: - Hour - Day - Week - Month - Period forecastDays: type: integer minimum: 0 comparisonPeriod: type: object properties: startDate: type: string nullable: true format: date-time endDate: type: string nullable: true format: date-time enabled: type: boolean chartType: type: string enum: - WATERFALL - TABLE - KPI_BREAKDOWN required: - startDate - endDate - enabled - chartType required: - aggBy queries: type: array items: oneOf: - type: object properties: type: type: string enum: - condition expression: type: string minLength: 1 name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE required: - type - expression - name - colorIndex - chartType - type: object properties: type: type: string enum: - formula formula: type: string name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window shiftAmount: type: integer shiftUnit: type: string enum: - DAY - WEEK - MONTH required: - type - formula - name - colorIndex - chartType - type: object properties: type: type: string enum: - metric metricId: type: string rawMetric: type: string groupBy: anyOf: - type: string - type: array items: type: string minLength: 1 - nullable: true type: string enum: - null unitOverride: type: string aggregator: type: string enum: - SUM - AVG - MAX - MIN reducer: type: string enum: - SUM - AVG - MAX - MIN name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE colorPalette: type: string enum: - DEFAULT - PIYG - RDYLBU - CLASSIC default: DEFAULT rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window shiftAmount: type: integer shiftUnit: type: string enum: - DAY - WEEK - MONTH required: - type - metricId - aggregator - name - colorIndex - chartType - type: object properties: type: type: string enum: - cost groupBy: anyOf: - type: string - type: array items: type: string minLength: 1 - nullable: true type: string enum: - null aggregator: type: string enum: - SUM - AVG - MAX - MIN currency: type: string enum: - USD - EUR - GBP - CNY - KRW whereClause: type: object properties: {} additionalProperties: {} metricId: type: string enum: - cost - effective_cost - list_cost - contracted_cost - unblended_cost - net_unblended_cost - amortized_cost - net_amortized_cost extendDashboardConditions: type: boolean default: true name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 reducer: type: string enum: - SUM - AVG - MAX - MIN visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE colorPalette: type: string enum: - DEFAULT - PIYG - RDYLBU - CLASSIC default: DEFAULT rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window excludeGroupByValue: type: object properties: source: type: object properties: type: type: string enum: - indexation required: - type additionalProperties: false required: - source additionalProperties: false description: >- Exclude group-by values already present in the billing-stats indexation catalog before the query window. HTTP API only; not available on MCP query. shiftAmount: type: integer shiftUnit: type: string enum: - DAY - WEEK - MONTH required: - type - aggregator - whereClause - name - colorIndex - chartType - type: object properties: type: type: string enum: - usage whereClause: type: object properties: {} additionalProperties: {} aggregator: type: string enum: - SUM - AVG - MAX - MIN groupBy: anyOf: - type: string - type: array items: type: string minLength: 1 - nullable: true type: string enum: - null metricId: type: string name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 reducer: type: string enum: - SUM - AVG - MAX - MIN visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE colorPalette: type: string enum: - DEFAULT - PIYG - RDYLBU - CLASSIC default: DEFAULT rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window excludeGroupByValue: type: object properties: source: type: object properties: type: type: string enum: - indexation required: - type additionalProperties: false required: - source additionalProperties: false description: >- Exclude group-by values already present in the billing-stats indexation catalog before the query window. HTTP API only; not available on MCP query. shiftAmount: type: integer shiftUnit: type: string enum: - DAY - WEEK - MONTH required: - type - whereClause - aggregator - metricId - name - colorIndex - chartType - type: object properties: type: type: string enum: - budget budgetId: type: string budgetLineId: type: string groupBy: anyOf: - type: string - type: array items: type: string minLength: 1 - nullable: true type: string enum: - null name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 virtualDimensionValue: type: string visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE colorPalette: type: string enum: - DEFAULT - PIYG - RDYLBU - CLASSIC default: DEFAULT rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window aggregator: type: string enum: - SUM - AVG - MAX - MIN default: SUM required: - type - budgetId - name - colorIndex - chartType - type: object properties: type: type: string enum: - externalMetric provider: type: string enum: - tsuga - bigquery - datadog - cloudwatch - s3 - amplitude - snowflake - cloudmonitoring - push integrationId: type: string minLength: 1 description: >- External metric integration ID from list_metrics(includeExternal: true). query: type: string minLength: 1 metricName: type: string default: '' aggregator: type: string enum: - SUM - AVG - MAX - MIN groupByFields: type: array items: type: string minLength: 1 maxItems: 7 default: [] conditions: type: string dateColumn: type: string minLength: 1 metricColumn: type: string minLength: 1 gapFillingMethod: type: string enum: - ZERO - FORWARD_FILL - LINEAR_INTERPOLATION - SPREAD name: type: string pattern: ^[A-Za-z_][A-Za-z0-9_]*$ alias: type: string minLength: 1 maxLength: 50 visible: type: boolean default: true colorIndex: type: number chartType: type: string enum: - BAR - LINE - AREA - WATERFALL - TABLE colorPalette: type: string enum: - DEFAULT - PIYG - RDYLBU - CLASSIC default: DEFAULT rollingAggregation: type: object properties: aggregator: type: string enum: - SUM - AVG - MAX - MIN window: type: object properties: preset: type: string enum: - MONTH - WEEK relativeDays: type: integer minimum: 1 required: - aggregator - window unitOverride: type: string required: - type - provider - integrationId - name - colorIndex - chartType discriminator: propertyName: type eventsFilter: type: object nullable: true properties: sources: type: array items: type: string enum: - custom - provider - github - api default: - custom - api githubSourceRepos: type: array items: type: string default: [] search: type: string default: '' bookmarkedEvents: type: array items: type: string scopeId: type: string nullable: true limitOverride: type: integer minimum: 1 maximum: 1000 displayOptions: type: object properties: sort: type: object properties: by: type: string minLength: 1 direction: type: string enum: - ASC - DESC default: DESC required: - by hideEmptyRows: type: boolean topN: type: integer minimum: 1 maximum: 100 showTotal: type: boolean precision: type: integer minimum: 0 maximum: 6 additionalProperties: false required: - period - queries - bookmarkedEvents required: - type - request - type: object properties: type: type: string enum: - text textContent: type: string default: '' required: - type discriminator: propertyName: type required: - key - x - 'y' - w - h - title - source required: - name - type - conditions - widgets responses: '201': description: Dashboard created content: application/json: schema: $ref: '#/components/schemas/DashboardIdCreated' '400': description: Scope not found or invalid payload content: application/json: schema: $ref: '#/components/schemas/DashboardError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' '403': description: Team membership required content: application/json: schema: $ref: '#/components/schemas/DashboardError' security: - bearerAuth: [] components: schemas: DashboardIdCreated: type: object properties: dashboardId: type: string required: - dashboardId DashboardError: type: object properties: error: type: string required: - error Unauthorized: type: object properties: error: type: string description: Unauthorized error message required: - error 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.