billing.costs.query

Cost over time, grouped and filtered by any dimension

POST /billing/api/cost-explorer/queryIAM billing:GetCostAndUsageRead

Dimensions: service, usageType, resource, resourceType, region, zone, project, tag (with tagKey), creator. Returns the stacked series, group totals vs the previous period of equal length, top movers by group and by resource, anomaly hints with the rule spelled out, a month-end forecast, discounts and credits, every billed resource with idle/detached/untagged hints, and the budgets. Amounts are EUR strings at 8 decimal places, exact. A read behind a POST: nothing is written.

Request syntax

POST /billing/api/cost-explorer/query
{
  "start": "string",
  "end": "string",
  "granularity": "enum",
  "groupBy": "object",
  "filters": "array of json",
  "maxGroups": "number"
}

Request body

  • startRequired

    string

    First day of the window, YYYY-MM-DD, UTC, inclusive

    Constraints: /^\d{4}-\d{2}-\d{2}$/

  • endRequired

    string

    Last day of the window, YYYY-MM-DD, UTC, inclusive; not before start, and the window is at most 400 days

    Constraints: /^\d{4}-\d{2}-\d{2}$/

  • granularityOptional

    enum

    Width of each bar: hour (windows of at most 14 days), day (default) or month

    One of: hour, day, month

    Default: "day"

  • groupByOptional

    object

    What the bars are stacked by: {dimension, tagKey}; default {dimension: service}

    Constraints: JSON

    Default: {"dimension":"service"}

  • filtersOptional

    array of json

    Narrow to rows matching every filter, at most 20: {dimension, values, tagKey, exclude}; default none

    Default: []

  • maxGroupsOptional

    number

    Groups drawn on their own, 1–50 (default 8); the rest are summed into "Other"

    Constraints: integer, 1-50

    Default: 8

Response

200 with query (as resolved, defaults filled), window { from, to, previousFrom, previousTo }, groupByLabel, total, previousTotal, changePercent, groups, series, movers { byGroup, byResource }, anomalies, forecast (null when the window does not reach into the current month), adjustments { gross, discounts, credits, net, grants, note }, resources, dimensions (the values each dimension takes, for filters), tagKeys, budgets (empty without billing:GetBudgets), notices (filter values that matched nothing) and generatedAt. 403 when grouping or filtering by provider without iam:UpdateOrganization.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow billing:GetCostAndUsage on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud billing costs query --start example --end example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_billing_costs_query.