> ## Documentation Index > Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cost query > Grouped and time-series cost breakdown for a period, with optional stacking and dimension filters. With format=csv or format=xlsx the response is a file with one row per leaf group and billing currency, every group included (group_limit and group_offset do not apply), followed by one total row per currency. Amounts are in the currency the spend was billed in. Exports are capped at 50000 rows. ## OpenAPI ````yaml /api-reference/costgraph/openapi.json get /api/v1/tenant/cost/query openapi: 3.0.0 info: description: Read and manage your CostGraph organization, spend, alerts, and settings. title: CostGraph API contact: {} version: '1.0' servers: - url: https://api.costgraph.ai security: [] tags: - name: ai x-group: AI - name: ai-serving x-group: AI serving - name: anomalies x-group: Anomalies - name: auth x-group: Auth - name: billing x-group: Billing - name: billing-export x-group: Billing export - name: budgets x-group: Budgets - name: ci x-group: CI - name: compute-recommendations x-group: Compute recommendations - name: config x-group: Config - name: cost x-group: Cost - name: gpus x-group: GPUs - name: graphai x-group: Graph AI - name: infracost x-group: Infracost - name: integrations x-group: Integrations - name: invitations x-group: Invitations - name: kubernetes-clusters x-group: Kubernetes clusters - name: marketplace x-group: Marketplace - name: network-requests x-group: Network requests - name: notifications x-group: Notifications - name: oauth x-group: OAuth - name: oauth-clients x-group: OAuth clients - name: opencost x-group: OpenCost - name: organization x-group: Audit log - name: organizations x-group: Organizations - name: placement-alternatives x-group: Placement alternatives - name: reports x-group: Reports - name: service-map x-group: Service map - name: settings x-group: Settings - name: sso x-group: Single sign-on - name: tenants x-group: Tenants - name: user x-group: Users - name: virtual-machines x-group: Virtual machines - name: virtual-tags x-group: Virtual tags - name: workflows x-group: Workflows paths: /api/v1/tenant/cost/query: get: tags: - cost summary: Cost query description: >- Grouped and time-series cost breakdown for a period, with optional stacking and dimension filters. With format=csv or format=xlsx the response is a file with one row per leaf group and billing currency, every group included (group_limit and group_offset do not apply), followed by one total row per currency. Amounts are in the currency the spend was billed in. Exports are capped at 50000 rows. parameters: - description: Tenant ID name: X-CostGraph-Tenant-ID in: header required: true schema: type: string - description: Cost period; defaults to month_to_date name: period in: query schema: type: string enum: - month_to_date - last_7d - last_30d - calendar_month - custom - description: >- Closed calendar month in YYYY-MM format; required when period=calendar_month name: month in: query schema: type: string - description: Window start in RFC3339 format; required when period=custom name: start in: query schema: type: string - description: Window end in RFC3339 format; required when period=custom name: end in: query schema: type: string - description: >- ISO 4217 code to express every amount in, converted at each day's exchange rate; defaults to the currency most of the selected period's spend was billed in, or USD when none dominates name: reporting_currency in: query schema: type: string - description: >- Ordered, comma-separated dimensions to group by; nested into a tree (e.g. provider,region,resource_type). Fixed dimensions: provider, resource_type, service_category, service_subcategory, service, region, availability_zone, resource, sku_id, sku_meter, charge_category, charge_description, pricing_category, pricing_unit, usage_unit, billing_account_id, sub_account, sub_account_type, invoice_id, invoice_issuer, publisher, currency. Tag and virtual-tag keys are also accepted as tag:, and provider extension keys as extension:; those keys are per-tenant or per-provider so they are not enumerable here name: group_by in: query required: true schema: type: string - description: >- Dimension to stack the time series by; accepts any dimension group_by accepts, including tag: and extension: name: stack_by in: query schema: type: string - description: >- Cost layer; defaults to billed. ci returns CI runner job rows, including each job's share of a vendor bill. name: layer in: query schema: type: string enum: - billed - allocation - ci - description: >- Maximum groups returned per level of the group tree; defaults to 100. Groups beyond the limit are combined into one final entry per level, marked other=true and carrying the folded group count name: group_limit in: query schema: type: integer - description: >- Number of top-level groups to skip, for paging past group_limit; deeper levels are not paged. The trailing other entry counts the groups left after this page name: group_offset in: query schema: type: integer - description: >- Case-insensitive text matched against the values and names of the grouped dimensions; totals, groups and series cover only matching rows, and totals.searchSharePct gives their share of the unsearched total name: search in: query schema: type: string - description: >- Response format; defaults to json. csv and xlsx download the full group table as a file name: format in: query schema: type: string enum: - json - csv - xlsx - description: >- Break every group down by sub-account, returning the top spenders plus a rollup of the rest and, where the group is only partly attributed, the unassigned remainder name: include_sub_accounts in: query schema: type: boolean - description: >- Repeated key:value dimension filter, repeat a key to match any of its values, e.g. filter=provider:aws&filter=provider:gcp. Keys are the same dimensions group_by accepts: provider, resource_type, service_category, service_subcategory, service, region, availability_zone, resource, sku_id, sku_meter, charge_category, charge_description, pricing_category, pricing_unit, usage_unit, billing_account_id, sub_account, sub_account_type, invoice_id, invoice_issuer, publisher, currency, plus per-tenant tag and virtual-tag keys as filter=tag:: and provider extension keys as filter=extension::. Prefix a dimension with has: for rows where it resolves at all, e.g. filter=has:tag:owner, filter=has:extension:x_ProjectId or filter=has:region. Prefix a dimension with no: for rows where it does not resolve, e.g. filter=no:tag:owner or filter=no:region. Prefix a dimension with not: to drop the given values, keeping rows where it does not resolve, repeat it to drop several, e.g. filter=not:provider:aws&filter=not:provider:gcp or filter=not:tag:team:platform; it combines with a plain filter on the same dimension. A filter_= query parameter is equivalent name: filter in: query style: form explode: false schema: type: array items: type: string responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/responses.SuccessResponse' - type: object properties: data: $ref: '#/components/schemas/cost.QueryResult' text/csv: schema: allOf: - $ref: '#/components/schemas/responses.SuccessResponse' - type: object properties: data: $ref: '#/components/schemas/cost.QueryResult' application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: allOf: - $ref: '#/components/schemas/responses.SuccessResponse' - type: object properties: data: $ref: '#/components/schemas/cost.QueryResult' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' text/csv: schema: $ref: '#/components/schemas/responses.ErrorResponse' application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: $ref: '#/components/schemas/responses.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' text/csv: schema: $ref: '#/components/schemas/responses.ErrorResponse' application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: $ref: '#/components/schemas/responses.ErrorResponse' security: - BearerAuth: [] components: schemas: responses.SuccessResponse: type: object required: - message - status properties: data: {} message: type: string example: some message status: type: string example: success cost.QueryResult: type: object properties: byCurrency: description: >- Selected-period spend per billed currency, with the conversion applied to each. type: array items: $ref: '#/components/schemas/cost.CurrencyTotal' categoryTotals: description: |- Spend broken down by charge category for the selected and previous periods. type: array items: $ref: '#/components/schemas/cost.CategoryTotal' days: description: |- Every calendar day in the selected period, in order, for aligning Series against a chart axis. type: array items: type: string facets: description: Available filter values for each dimension, for building filter UI. allOf: - $ref: '#/components/schemas/cost.Facets' x-nullable: 'false' groups: description: |- Top-level groups, one per distinct value of the first group_by dimension, sorted by current spend descending so Groups[0] is the largest spender. type: array items: $ref: '#/components/schemas/cost.Group' netCurrent: description: |- Net spend (gross plus credits) for the selected period, in the reporting currency. type: number x-semantic: costAmount netPrevious: description: |- Net spend (gross plus credits) for the previous period, same currency. type: number x-semantic: costAmount previousComparable: description: |- False when the previous period has no comparable data (e.g. the tenant did not exist yet), in which case ChangePct and ChangeAmount fields throughout the response are not meaningful. type: boolean reportingCurrency: description: >- ISO 4217 code every converted amount in the response is expressed in. type: string series: description: |- Daily cost points covering the selected period, one per day per stack when the request stacks the series. type: array items: $ref: '#/components/schemas/cost.SeriesPoint' stackLabels: description: |- Display labels for stack keys, keyed by the raw stack value. Absent when the request did not stack the series. type: object additionalProperties: type: string totals: description: Whole-report totals for the selected period. allOf: - $ref: '#/components/schemas/cost.Totals' x-nullable: 'false' unconverted: description: >- Selected-period spend with no exchange rate on record, left out of every total. type: array items: $ref: '#/components/schemas/cost.UnconvertedTotal' responses.ErrorResponse: type: object required: - message - status properties: message: type: string example: some message status: type: string example: error cost.CurrencyTotal: type: object properties: convertedTotal: description: >- The part of NativeTotal that could be converted, in the reporting currency. type: number x-semantic: costAmount currency: description: ISO 4217 code the spend was billed in. type: string effectiveRate: description: >- Reporting-currency units per unit of Currency, blended over the days converted. Absent when nothing in this currency could be converted. type: number latestRateDate: description: >- Date of the most recent exchange rate applied. Absent when no rate was needed. type: string nativeTotal: description: >- Spend in the selected period in its billed currency, before conversion. type: number x-semantic: costAmount nearestRateUsed: description: >- Set when some of this spend predates the oldest exchange rate on record and was converted at the nearest later rate instead. type: boolean cost.CategoryTotal: type: object properties: chargeCategory: description: |- FOCUS charge category this total covers, e.g. "Usage", "Purchase", "Tax". type: string current: description: |- Gross spend in the selected period for this category, in the reporting currency. type: number x-semantic: costAmount previous: description: |- Gross spend in the comparable previous period for this category, same currency. type: number x-semantic: costAmount cost.Facets: type: object properties: extensions: description: |- Provider extension values present in the underlying rows, keyed by extension key. Extension keys are provider-specific. type: object additionalProperties: type: array items: type: string provider: description: |- Provider values present in the underlying rows, for building a provider filter. type: array items: $ref: '#/components/schemas/cost.FacetOption' region: description: Region values present in the underlying rows. type: array items: $ref: '#/components/schemas/cost.FacetOption' resource_type: description: Resource type values present in the underlying rows. type: array items: $ref: '#/components/schemas/cost.FacetOption' service_category: description: Service category values present in the underlying rows. type: array items: $ref: '#/components/schemas/cost.FacetOption' sub_account: description: |- Sub-account values present in the underlying rows. Only populated when the request set include_sub_accounts=true. type: array items: $ref: '#/components/schemas/cost.FacetOption' tags: description: |- Tag values present in the underlying rows, keyed by tag key. Absent when no tag filters apply to the report. type: object additionalProperties: type: array items: type: string truncated: description: |- Names of the facets above whose value list was cut off at FacetValueLimit distinct values. Absent when no facet was truncated. type: array items: type: string cost.Group: type: object properties: billedCost: description: Spend on the billed-cost basis, in the reporting currency. type: number x-semantic: costAmount byCurrency: description: >- Selected-period spend split by the currency it was billed in, one entry per currency, so a single-currency row has exactly one. type: array items: $ref: '#/components/schemas/cost.CurrencyAmount' changeAmount: description: |- Signed absolute change against the previous period, same currency. Positive means spend went up. type: number x-semantic: costAmount changePct: description: |- Signed percent change against the previous period, expressed as a percentage rather than a ratio. Positive means spend went up. type: number x-semantic: percentage chargeCategory: description: >- FOCUS charge category the spend falls under, e.g. "Usage", "Purchase", "Tax". type: string children: description: |- Child groups, one level of the group tree deeper, sorted by current spend descending so Children[0] is the largest child. Only populated when group_by names two or more comma-separated dimensions; nesting depth equals the number of dimensions requested. type: array items: $ref: '#/components/schemas/cost.Group' contractedCost: description: >- Spend on the contracted-rate basis (after negotiated discounts, before further credits), same currency. type: number x-semantic: costAmount count: type: integer current: description: Spend in the selected period, in the reporting currency. type: number x-semantic: costAmount dimension: description: |- Which dimension this level groups by, matching the group_by request parameter, e.g. "provider" or "resource". type: string key: description: |- The dimension value this group aggregates, e.g. a provider name or a tag value. Empty when Unallocated is set. type: string label: description: >- Display label for Key. Absent when the backend has no friendlier name than the key itself, in which case the caller should render Key. type: string listCost: description: |- Spend on the list-price basis (before negotiated discounts), same currency. type: number x-semantic: costAmount other: type: boolean possibleSavings: type: number x-semantic: costAmount previous: description: Spend in the comparable previous period, same currency. type: number x-semantic: costAmount pricingCategory: description: |- FOCUS pricing category the spend falls under, e.g. "Standard", "Dynamic", "Committed". type: string resourceId: description: |- Provider-assigned identifier of the underlying resource. Only populated when this level's Dimension is "resource". type: string x-semantic: resourceId resourceType: description: |- Resource type of the underlying rows, e.g. "instance" or "volume". Only populated when this level's Dimension is "resource". type: string service: description: Name of the billed service, e.g. "Amazon EC2" or "Compute Engine". type: string share: description: >- Percent (0-100) of the whole report's total spend, at every level of the group tree. A child's share is of the report total, not of its parent. type: number x-semantic: percentage skuMeter: description: SKU meter name backing the charge, when the provider reports one. type: string subAccountCount: description: |- Total number of distinct sub-accounts contributing to this group's spend, including ones folded into SubAccountOther. Only populated when include_sub_accounts=true. type: integer subAccountOther: description: |- Combined spend of sub-accounts excluded from SubAccounts because the result was truncated to the top N. Only populated when include_sub_accounts=true and truncation occurred. allOf: - $ref: '#/components/schemas/cost.SubAccountShare' subAccountUnassigned: description: >- Combined spend of rows with no sub-account value. Only populated when include_sub_accounts=true, unassigned spend exists, and at least one named sub-account is also present; absent when every row is unassigned. allOf: - $ref: '#/components/schemas/cost.SubAccountShare' subAccounts: description: |- Per-sub-account breakdown of this group's spend. Only populated when the request set include_sub_accounts=true. type: array items: $ref: '#/components/schemas/cost.SubAccountShare' unallocated: description: |- Set when the underlying rows had no value for this dimension (SQL NULL); Key is empty in that case. Absent rather than false, so a missing field means allocated. type: boolean unitPrice: description: |- Price per unit of UsageUnit, in the reporting currency. Present only when UsageUnit is set and UsageQuantity is non-zero. type: number x-semantic: costAmount unitPriceUnit: description: |- Unit UnitPrice is expressed per. Present only when UsageUnit is set and UsageQuantity is non-zero. type: string usageQuantity: description: |- Amount of usage consumed, counted in UsageUnit. Zero when the underlying rows have no usage quantity or mix incompatible units. type: number usageUnit: description: |- Unit UsageQuantity is counted in. Absent when the rows being summed use mixed units. type: string cost.SeriesPoint: type: object properties: cost: description: Spend for this day and stack, in the reporting currency. type: number x-semantic: costAmount day: description: Calendar day this point covers, midnight UTC. type: string stack: description: |- Stack key this point belongs to, matching the request's stack_by dimension. Empty when the request did not stack the series. type: string cost.Totals: type: object properties: changeAmount: description: Signed absolute change of Current against Previous, same currency. type: number x-semantic: costAmount changePct: description: |- Signed percent change of Current against Previous, expressed as a percentage rather than a ratio. Positive means spend went up. type: number x-semantic: percentage credits: description: |- Credit offset applied to Current, same currency. Normally negative, since a credit reduces spend; sign follows the ingested data. type: number x-semantic: costAmount creditsCoverPct: type: number x-semantic: percentage creditsPrevious: description: |- Credit offset applied to Previous, same currency. Normally negative; sign follows the ingested data. type: number x-semantic: costAmount current: description: |- Gross spend in the selected period, in the reporting currency. What the workload costs, and what rightsizing and anomaly detection act on. type: number x-semantic: costAmount dailyAverage: description: |- Current divided evenly across the days in the selected period, same currency. type: number x-semantic: costAmount monthToDate: type: number x-semantic: costAmount monthlyPace: type: number x-semantic: costAmount net: description: 'Current plus Credits: what the invoice for the selected period says.' type: number x-semantic: costAmount netPrevious: description: |- Previous plus CreditsPrevious: what the invoice for the previous period said. type: number x-semantic: costAmount previous: description: Gross spend in the comparable previous period, same currency. type: number x-semantic: costAmount searchSharePct: type: number x-semantic: percentage cost.UnconvertedTotal: type: object properties: currency: description: ISO 4217 code of spend that has no exchange rate on record. type: string nativeTotal: description: >- Spend in the selected period left out of every converted total, in Currency. type: number x-semantic: costAmount cost.FacetOption: type: object properties: label: description: |- Display label for Value. Absent when the backend has no friendlier name than the value itself. type: string value: description: Raw dimension value to send back as a filter. type: string cost.CurrencyAmount: type: object properties: convertedTotal: description: >- The same spend in the reporting currency. Zero when no exchange rate exists. type: number x-semantic: costAmount currency: description: ISO 4217 code the spend was billed in. type: string nativeTotal: description: Spend in Currency, before conversion. type: number x-semantic: costAmount cost.SubAccountShare: type: object properties: billedCost: description: Spend on the billed-cost basis, in the reporting currency. type: number x-semantic: costAmount byCurrency: description: >- Selected-period spend split by the currency it was billed in, one entry per currency, so a single-currency row has exactly one. type: array items: $ref: '#/components/schemas/cost.CurrencyAmount' changeAmount: description: |- Signed absolute change against the previous period, same currency. Positive means spend went up. type: number x-semantic: costAmount changePct: description: |- Signed percent change against the previous period, expressed as a percentage rather than a ratio. Positive means spend went up. type: number x-semantic: percentage chargeCategory: description: >- FOCUS charge category the spend falls under, e.g. "Usage", "Purchase", "Tax". type: string contractedCost: description: >- Spend on the contracted-rate basis (after negotiated discounts, before further credits), same currency. type: number x-semantic: costAmount count: description: |- Number of distinct sub-accounts folded into this share. Only set on SubAccountOther; always zero on SubAccountUnassigned. type: integer current: description: Spend in the selected period, in the reporting currency. type: number x-semantic: costAmount id: description: Provider-assigned identifier of the sub-account. type: string x-semantic: resourceId listCost: description: |- Spend on the list-price basis (before negotiated discounts), same currency. type: number x-semantic: costAmount name: description: Display name of the sub-account, when the provider reports one. type: string previous: description: Spend in the comparable previous period, same currency. type: number x-semantic: costAmount pricingCategory: description: |- FOCUS pricing category the spend falls under, e.g. "Standard", "Dynamic", "Committed". type: string service: description: Name of the billed service, e.g. "Amazon EC2" or "Compute Engine". type: string share: description: >- Percent (0-100) of the whole report's total spend, at every level of the group tree. A child's share is of the report total, not of its parent. type: number x-semantic: percentage type: description: |- Provider-specific sub-account kind, e.g. "linked account" or "project". type: string unitPrice: description: |- Price per unit of UsageUnit, in the reporting currency. Present only when UsageUnit is set and UsageQuantity is non-zero. type: number x-semantic: costAmount unitPriceUnit: description: |- Unit UnitPrice is expressed per. Present only when UsageUnit is set and UsageQuantity is non-zero. type: string usageQuantity: description: |- Amount of usage consumed, counted in UsageUnit. Zero when the underlying rows have no usage quantity or mix incompatible units. type: number usageUnit: description: |- Unit UsageQuantity is counted in. Absent when the rows being summed use mixed units. type: string securitySchemes: BearerAuth: description: Enter "Bearer {token}" type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.