---
title: "Query grouped usage cost subtotals for an account."
method: POST
path: "/v1/accounts/{account_id}/usageCosts:query"
tags: ["gateway.openapi_Gateway"]
---

# Query grouped usage cost subtotals for an account.

`POST /v1/accounts/{account_id}/usageCosts:query`

## Request

- Base URL: `https://api.fireworks.ai`
- URL: `https://api.fireworks.ai/v1/accounts/{account_id}/usageCosts:query`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/fw-ai-external/apis/gateway-rest-api/docs/v1/accounts/:account_id/usageCosts:query/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns rated dollar subtotals for usage over a time range, grouped by up to two of: HOUR, DAY, MODEL, USER, or API_KEY. Unlike `GET /billingUsage` (metered quantities) and `GET /billing/summary` (line items by billing category), this endpoint returns *rated costs* broken down by caller-supplied dimensions, with pagination and an account-wide `subtotal`. Requires account administrator access for `ACCOUNT` scope; `SELF` scope returns costs for the authenticated principal only.

## Path parameters

- `account_id` string, required

## Request body

- GatewayGatewayQueryUsageCostsBody: Request for grouped usage cost subtotals over a time range.
  - `startTime` string, date-time: Inclusive lower bound for usage event timestamps.
  - `endTime` string, date-time: Exclusive upper bound for usage event timestamps.
  - `scope` 'SCOPE_UNSPECIFIED' | 'ACCOUNT' | 'SELF'
  - `groupBy` QueryUsageCostsRequestDimension[]: Dimensions to group by. At most two dimensions may be combined. HOUR and DAY are mutually exclusive. SESSION is intentionally filter-only to prevent high-cardinality enumeration.
  - `filter` GatewayUsageCostFilter: Exact property filters for a usage cost query. Populated fields are ANDed.
    - `model` string
    - `user` string
    - `apiKeyId` string: Stable API key ID. This is never plaintext key material.
    - `sessionId` string: Exact client session ID. Valid only for self-scoped queries. This value is used only as a filter and is never returned in the response.
  - `pageSize` integer: For paginated queries, the maximum number of grouped values to return. A page can contain more rows when each value spans multiple time buckets. Zero uses the server default; values above the maximum are clamped.
  - `pageToken` string: Opaque token from a previous response. Set this to retrieve the next page while keeping all other request fields unchanged.

## Response `200`

A successful response.

- GatewayQueryUsageCostsResponse
  - `rows` GatewayUsageCostRow[]: Cost rows for the requested dimensions. A successful response contains at most 10,100 rows and is limited to 4 MiB.
    - `dimensions` GatewayUsageCostDimensions: Grouping values for one usage cost row. Fields not requested in group_by are left empty.
      - `startTime` string, date-time: Start of the UTC HOUR or DAY bucket intersected with the requested range. The first bucket may start at the request's start_time.
      - `model` string: Canonical model resource name.
      - `user` string: User resource name.
      - `apiKeyId` string: Stable API key ID.
      - `unattributedDimensions` QueryUsageCostsRequestDimension[]: Requested dimensions that were absent from the billing event. More than one dimension may be absent when the query groups by two dimensions.
      - `unknownModel` boolean: Whether a populated billing model could not be mapped to a public model. The internal model value is not exposed.
    - `subtotal` TypeMoney: Represents an amount of money with its currency type.
      - `currencyCode` string: The three-letter currency code defined in ISO 4217.
      - `units` string, int64: The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
      - `nanos` integer: Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
  - `nextPageToken` string: Opaque token for the next page. Empty when no additional page is available.
  - `subtotal` TypeMoney: Represents an amount of money with its currency type.
    - `currencyCode` string: The three-letter currency code defined in ISO 4217.
    - `units` string, int64: The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar.
    - `nanos` integer: Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999 inclusive. If `units` is positive, `nanos` must be positive or zero. If `units` is zero, `nanos` can be positive, zero, or negative. If `units` is negative, `nanos` must be negative or zero. For example $-1.75 is represented as `units`=-1 and `nanos`=-750,000,000.
  - `evaluationTime` string, date-time: Time when this result was evaluated.
  - `attributionCompleteness` 'ATTRIBUTION_COMPLETENESS_UNSPECIFIED' | 'COMPLETE' | 'INCOMPLETE' | 'UNKNOWN'

## Changes

- **2026-10-16** `3bf245180173`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fw-ai-external/apis/gateway-rest-api/changes/v1/accounts/:account_id/usageCosts:query/post.md)

---

[API](https://skmtc.dev/fw-ai-external/apis/gateway-rest-api.md) - [All operations](https://skmtc.dev/fw-ai-external/apis/gateway-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fw-ai-external/apis/gateway-rest-api/revisions/3bf245180173?raw)