Returns usage-ledger consumption and gross cost from the same provider used by Replit's Usage settings page. Omit workspaceId, groupId, userId, and projectId for Account-wide totals. Filters are intersected when combined.

groupId requires workspaceId and filters usage to users who are active group members when the request is processed. Deleted or disabled memberships, deleted users, and support seats are excluded. An explicit userId is intersected with current group membership. Users can belong to multiple groups, so totals from separate group requests are not additive. Ungrouped and unattributed usage is excluded from group-filtered requests. groupId supports totals, groupBy=member, groupBy=project, groupBy=conversations, and groupBy=timeseries; it cannot be combined with groupBy=workspace. The response does not repeat the group ID or expose group names or internal Account identifiers.

Example: GET /v1/usage?workspaceId=workspace123&groupId=groupEngineering&groupBy=member

Omit all range parameters for the current billing period. billingPeriod cannot be combined with startTime or endTime. Custom ranges require both startTime and endTime, use inclusive start and exclusive end boundaries, and cannot exceed 366 days. groupBy adds one breakdown; granularity is valid only with groupBy=timeseries. groupBy=member includes every selected metric type and is not limited to Agent usage. With groupBy=project, breakdownBy=member adds a complete member breakdown and explicit unattributed-member metrics to every selected project. Pagination counts projects, and members are ordered by descending cost with userId as the tie-breaker. Requests without breakdownBy retain the existing response shape. Example: GET /v1/usage?groupBy=project&breakdownBy=member&limit=100 Breakdown responses are limited to 10,000 project/member/metric detail rows and 8 MiB of JSON. A result exceeding these bounds returns 422 usage_breakdown_too_large without partial data. Reduce limit, narrow the interval, or apply filters to retry. A cursor can be retried with a smaller limit; adding or removing breakdownBy invalidates the cursor. groupBy=conversations returns one environmentType=conversation group. attributableTotalCostUsd is conversation spend, and unattributableTotalCostUsd is all remaining spend for the selected filters.

Recent usage can arrive after a response. Costs are gross usage-ledger values, not settled invoice totals. Account credits, discounts, and net charges are intentionally excluded.