{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Returns cost and usage data for a single Cloudflare account, aligned\nwith the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/)\nCost and Usage dataset specification.\n\nThis is the filterable counterpart to `GET` on the same path. It is a\nread-only operation and requires only the `#billing:read` permission;\n`POST` is used so that filter criteria can be supplied in a request body\nrather than in the query string.\n\nEach record represents one billable metric for one account on one day.\nThis includes all metered usage, including usage that falls within\nfree-tier allowances and may result in zero cost.\n\n**Note:** Cost and pricing fields are populated only when `Metric`\nis `cost`; otherwise they are absent from responses.\n\nThe request body is optional. When it is omitted, or when `TimePeriod`\nis omitted, the range defaults to the start of the current month through\ntoday. The maximum date range is 31 days.\n\nFilters of different kinds are combined with AND. Values within one tag\nfilter are combined with OR. Filter values that do not match usage\nproduce an empty result set.\n\nResults can be grouped by up to two groups, in any combination of\ndimension keys and resource-tag keys. Tag groups are returned in the\n`Tags` field. Usage without a requested tag remains in an untagged\ngroup, with that key omitted from `Tags`.\n\nRequests that use tag filtering or tag grouping return HTTP 400 when the\nunderlying usage data source does not support tags.\n\nRequests that use dimension grouping return HTTP 400 when the\nunderlying usage data source does not support dimensions.\n","properties":{"path":{"type":"object","properties":{"account_id":{"$ref":"#/definitions/billable-usage-api_identifier","description":"Identifies the Cloudflare account."}},"required":["account_id"],"additionalProperties":false},"body":{"$ref":"#/definitions/billable-usage-api_v2_usage_query"}},"required":["path"],"additionalProperties":false,"definitions":{"billable-usage-api_identifier":{"description":"Represents a Cloudflare resource identifier tag.","type":"string","maxLength":32,"pattern":"^[0-9a-f]{32}$","examples":["023e105f4ecef8ad9ca31a8372d0c353"]},"billable-usage-api_v2_usage_query":{"description":"Filter criteria for a usage query. Every field is optional; an empty object is equivalent to omitting the body entirely. Unknown fields are rejected.","type":"object","properties":{"FilterBy":{"$ref":"#/definitions/billable-usage-api_v2_filter_by"},"GroupBy":{"description":"Grouping definitions used to split result rows. At most two unique keys may be supplied.","type":"array","items":{"$ref":"#/definitions/billable-usage-api_v2_group_by"},"maxItems":2,"uniqueItems":true},"Metric":{"description":"Type of cost/usage records to retrieve. `usage` returns unrated usage quantities. `cost` returns rated usage with cost and pricing fields; it is available only on `POST` account usage and only when the underlying usage data source is ClickHouse (other sources return an empty result set). Requests that combine `cost` with `GroupBy` or `FilterBy.Tags` return HTTP 400. Unrelated to `FilterBy.BillableMetricIds`. Defaults to `usage` when omitted.","type":"string","default":"usage","enum":["usage","cost"],"examples":["usage"]},"TimePeriod":{"$ref":"#/definitions/billable-usage-api_v2_time_period"}},"additionalProperties":false},"billable-usage-api_v2_filter_by":{"description":"Usage filters. Filters of different kinds are combined with AND, so a record must match every filter present to be returned.","type":"object","properties":{"BillableMetricIds":{"description":"Restrict results to rows whose `x_BillableMetricId` matches one of these billable metric ids (e.g. `workers_standard_requests`). Values must be unique.","type":"array","items":{"maxLength":128,"type":"string"},"maxItems":20,"uniqueItems":true,"examples":[["workers_standard_requests","http_transferred_bytes"]]},"ProductFamilyIds":{"description":"Restrict results to billable metrics belonging to these product families. Values must be unique UUIDs.","type":"array","items":{"format":"uuid","type":"string"},"maxItems":10,"uniqueItems":true,"examples":[["3f1b9c1e-0000-4000-8000-000000000000"]]},"Tags":{"description":"Restrict results by resource tags. Filters for different keys are combined with AND, while values within one filter are combined with OR. Keys must be unique and are case-sensitive.","type":"array","items":{"$ref":"#/definitions/billable-usage-api_v2_tag_filter"},"maxItems":10,"uniqueItems":true}},"additionalProperties":false},"billable-usage-api_v2_group_by":{"description":"A definition used to split result rows. TAG groups by a case-sensitive resource-tag key. DIMENSION groups by a usage dimension key — account_id, zone_id and region are the documented keys, and any other dimension key carried by the usage data is accepted and returned under that same key.","type":"object","properties":{"Key":{"description":"Case-sensitive resource-tag key (for TAG) or dimension key (for DIMENSION), e.g. team, region, account_id or zone_id.","type":"string","maxLength":256,"minLength":1,"examples":["region"]},"Type":{"description":"Group category.","type":"string","enum":["TAG","DIMENSION"],"examples":["DIMENSION"]}},"additionalProperties":false,"required":["Type","Key"]},"billable-usage-api_v2_time_period":{"description":"Charge period to query, i.e. when consumption happened, not when it was billed. `From` is inclusive and `To` is exclusive. `From` and `To` must be supplied together; supplying one without the other is an error. When both are omitted the range defaults to the start of the current month through today.","type":"object","properties":{"From":{"description":"Start of the range (ISO 8601). Required if `To` is set.","type":"string","format":"date-time","examples":["2025-05-01T00:00:00Z"]},"To":{"description":"End of the range (ISO 8601). Required if `From` is set. Must be after `From` and no more than 31 days after it.","type":"string","format":"date-time","examples":["2025-05-31T00:00:00Z"]}},"additionalProperties":false},"billable-usage-api_v2_tag_filter":{"description":"Values accepted for one resource-tag key.","type":"object","properties":{"Key":{"description":"Case-sensitive resource-tag key.","type":"string","maxLength":256,"minLength":1,"examples":["team"]},"Values":{"description":"Tag values to match. Values are combined with OR and must be unique. An empty string matches a key-only tag.","type":"array","items":{"maxLength":1024,"type":"string"},"maxItems":20,"minItems":1,"uniqueItems":true,"examples":[["fintech"]]}},"additionalProperties":false,"required":["Key","Values"]}}},"name":"Query Account Usage (Version 2, Alpha, Restricted)","id":"cloudflare.billable-usage-v2-query-account-usage","example":{"path":{"account_id":"023e105f4ecef8ad9ca31a8372d0c353"}},"maxRequests":1,"summary":false}}