> ## Documentation Index > Fetch the complete documentation index at: https://docs.fireworks.ai/llms.txt > Use this file to discover all available pages before exploring further. # Query grouped usage cost subtotals for an account. > 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. ## OpenAPI ````yaml post /v1/accounts/{account_id}/usageCosts:query openapi: 3.1.0 info: title: Gateway REST API version: 5.10.0 servers: - url: https://api.fireworks.ai security: - BearerAuth: [] tags: - name: AccountService - name: DeploymentService - name: Gateway - name: ModelService - name: TrainingService paths: /v1/accounts/{account_id}/usageCosts:query: post: tags: - Gateway summary: Query grouped usage cost subtotals for an account. description: >- 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. operationId: Gateway_QueryUsageCosts parameters: - name: account_id in: path required: true description: The Account Id schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/gatewayGatewayQueryUsageCostsBody' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/gatewayQueryUsageCostsResponse' components: schemas: gatewayGatewayQueryUsageCostsBody: type: object properties: startTime: type: string format: date-time description: Inclusive lower bound for usage event timestamps. endTime: type: string format: date-time description: Exclusive upper bound for usage event timestamps. scope: $ref: '#/components/schemas/gatewayQueryUsageCostsRequestScope' description: >- ACCOUNT requires account administrator access. SELF derives the user ID from the authenticated principal. groupBy: type: array items: $ref: '#/components/schemas/QueryUsageCostsRequestDimension' description: >- 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: $ref: '#/components/schemas/gatewayUsageCostFilter' description: Optional exact-match filters. All populated fields are ANDed. pageSize: type: integer format: int32 description: >- 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: type: string description: >- Opaque token from a previous response. Set this to retrieve the next page while keeping all other request fields unchanged. maxLength: 4096 description: Request for grouped usage cost subtotals over a time range. gatewayQueryUsageCostsResponse: type: object properties: rows: type: array items: $ref: '#/components/schemas/gatewayUsageCostRow' type: object description: >- Cost rows for the requested dimensions. A successful response contains at most 10,100 rows and is limited to 4 MiB. nextPageToken: type: string description: >- Opaque token for the next page. Empty when no additional page is available. subtotal: $ref: '#/components/schemas/typeMoney' description: Subtotal for the complete query. evaluationTime: type: string format: date-time description: Time when this result was evaluated. readOnly: true attributionCompleteness: $ref: '#/components/schemas/QueryUsageCostsResponseAttributionCompleteness' description: >- Whether the result may omit usage without a user ID. INCOMPLETE means the query filters by user, so historical unattributed usage may be excluded. The amount excluded is unknown. readOnly: true gatewayQueryUsageCostsRequestScope: type: string enum: - SCOPE_UNSPECIFIED - ACCOUNT - SELF default: SCOPE_UNSPECIFIED QueryUsageCostsRequestDimension: type: string enum: - DIMENSION_UNSPECIFIED - HOUR - MODEL - USER - API_KEY - DAY default: DIMENSION_UNSPECIFIED gatewayUsageCostFilter: type: object properties: model: type: string title: |- Canonical model resource name. Format: accounts/{account}/models/{model} user: type: string title: |- User resource name. Valid only for account-scoped queries. Format: accounts/{account}/users/{user} apiKeyId: type: string description: Stable API key ID. This is never plaintext key material. sessionId: type: string description: >- 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. description: >- Exact property filters for a usage cost query. Populated fields are ANDed. gatewayUsageCostRow: type: object properties: dimensions: $ref: '#/components/schemas/gatewayUsageCostDimensions' subtotal: $ref: '#/components/schemas/typeMoney' description: >- Usage priced with the applicable subscription prices. This excludes fixed fees and invoice-level discounts, minimums, credits, and taxes. description: One row in a usage cost query. typeMoney: type: object properties: currencyCode: type: string description: The three-letter currency code defined in ISO 4217. units: type: string format: int64 description: >- The whole units of the amount. For example if `currencyCode` is `"USD"`, then 1 unit is one US dollar. nanos: type: integer format: int32 description: >- 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. description: Represents an amount of money with its currency type. QueryUsageCostsResponseAttributionCompleteness: type: string enum: - ATTRIBUTION_COMPLETENESS_UNSPECIFIED - COMPLETE - INCOMPLETE - UNKNOWN default: ATTRIBUTION_COMPLETENESS_UNSPECIFIED gatewayUsageCostDimensions: type: object properties: startTime: type: string format: date-time description: >- 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: type: string description: Canonical model resource name. user: type: string description: User resource name. apiKeyId: type: string description: Stable API key ID. unattributedDimensions: type: array items: $ref: '#/components/schemas/QueryUsageCostsRequestDimension' description: >- Requested dimensions that were absent from the billing event. More than one dimension may be absent when the query groups by two dimensions. readOnly: true unknownModel: type: boolean description: >- Whether a populated billing model could not be mapped to a public model. The internal model value is not exposed. readOnly: true description: >- Grouping values for one usage cost row. Fields not requested in group_by are left empty. securitySchemes: BearerAuth: type: http scheme: bearer description: >- Bearer authentication using your Fireworks API key. Format: Bearer bearerFormat: API_KEY ````