---
title: "Get Account usage and gross ledger cost"
method: GET
path: "/usage"
tags: ["Usage"]
---

# Get Account usage and gross ledger cost

`GET /usage`

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.
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.

## Query parameters

- `workspaceId` string
- `groupId` string
- `userId` string
- `projectId` string
- `billingPeriod` 'current' | 'previous'
- `startTime` string, date-time
- `endTime` string, date-time
- `type` string[]
- `groupBy` 'workspace' | 'member' | 'project' | 'conversations' | 'timeseries'
- `granularity` 'day'
- `limit` integer
- `cursor` string

## Response `200`

Usage summary.

- UsageResponse
  - `data` object, required
    - `interval` object, required — Resolved half-open UTC interval used for the query.
      - `startTime` string, date-time, required — Inclusive interval boundary.
      - `endTime` string, date-time, required — Exclusive interval boundary.
    - `currency` 'USD', required
    - `totalCostUsd` number, required — Gross ledger cost recorded for the requested filters before Account credits, discounts, and invoice adjustments.
    - `metrics` UsageMetric[], required
      - `id` 'agent' | 'replit_ai_integrations' | 'tools' | 'autoscale_deployment_compute' | 'autoscale_deployment' | 'autoscale_requests' | 'azure_container_app_usage' | 'azure_vm_compute' | 'always_on_deployment_compute' | 'scheduled_deployment_compute' | 'scheduled_deployment_executions' | 'deployment_data_transfer' | 'development_compute' | 'project_traffic' | 'project_storage' | 'production_database_compute' | 'production_database_storage' | 'production_database_logical_storage' | 'production_database_pitr_storage' | 'production_database_backup_storage' | 'assistant_edits' | 'agent_checkpoints' | 'object_storage_advanced_operations' | 'object_storage_basic_operations' | 'object_storage' | 'object_storage_data_transfer' | 'other', required — Stable public metric identifier. This value is independent of Replit's internal billing identifiers. Unmapped internal metrics are combined as other with no usage quantity.
      - `name` string, required — Customer-facing metric name.
      - `category` 'ai' | 'project_hosting' | 'project_traffic_and_data' | 'storage' | 'other', required — Coarse category shared with the Replit Usage settings page.
      - `usage` number, nullable, required — Native metered quantity, or null when the metric is pre-rated.
      - `usageUnit` string, nullable, required — Unit for usage, or null when the metric is pre-rated.
      - `costUsd` number, required — Gross ledger cost recorded before Account credits, discounts, and invoice adjustments.
    - `groupBy` 'workspace' | 'member' | 'project' | 'conversations' | 'timeseries' | 'null', nullable, required — Echoes the requested grouping, or null when totals only were requested.
    - `groups` UsageGroup[], required — Empty when groupBy is omitted. Entity groups are ordered by descending totalCostUsd; timeseries groups are ordered by ascending date; conversations returns one group.
      - `key` union, required
        - object
          - `workspaceId` string, required
        - object
          - `userId` string, required
        - object
          - `projectId` string, required
        - object
          - `date` string, date, required — UTC day for a timeseries group.
        - object
          - `environmentType` 'conversation', required — Constant key for usage attributed to conversations.
      - `totalCostUsd` number, required — Gross ledger cost attributable to this group.
      - `metrics` UsageMetric[], required
        - `id` 'agent' | 'replit_ai_integrations' | 'tools' | 'autoscale_deployment_compute' | 'autoscale_deployment' | 'autoscale_requests' | 'azure_container_app_usage' | 'azure_vm_compute' | 'always_on_deployment_compute' | 'scheduled_deployment_compute' | 'scheduled_deployment_executions' | 'deployment_data_transfer' | 'development_compute' | 'project_traffic' | 'project_storage' | 'production_database_compute' | 'production_database_storage' | 'production_database_logical_storage' | 'production_database_pitr_storage' | 'production_database_backup_storage' | 'assistant_edits' | 'agent_checkpoints' | 'object_storage_advanced_operations' | 'object_storage_basic_operations' | 'object_storage' | 'object_storage_data_transfer' | 'other', required — Stable public metric identifier. This value is independent of Replit's internal billing identifiers. Unmapped internal metrics are combined as other with no usage quantity.
        - `name` string, required — Customer-facing metric name.
        - `category` 'ai' | 'project_hosting' | 'project_traffic_and_data' | 'storage' | 'other', required — Coarse category shared with the Replit Usage settings page.
        - `usage` number, nullable, required — Native metered quantity, or null when the metric is pre-rated.
        - `usageUnit` string, nullable, required — Unit for usage, or null when the metric is pre-rated.
        - `costUsd` number, required — Gross ledger cost recorded before Account credits, discounts, and invoice adjustments.
    - `attributableTotalCostUsd` number, nullable, required — Sum attributable to entity or conversation groups before pagination, or null for totals and timeseries.
    - `unattributableTotalCostUsd` number, nullable, required — Difference between totalCostUsd and attributableTotalCostUsd, or null for totals and timeseries.
    - `pagination` object, nullable, required — Group page metadata, or null when groupBy is omitted. Conversation grouping returns one complete page.
      - `nextCursor` string, nullable, required — Opaque cursor for the next groups page, or null when no page remains.
      - `hasMore` boolean, required
      - `totalCount` integer, required — Total groups matching the request before pagination.

## Other responses

- `400` — The request parameters are invalid.
- `401` — The API key is missing, malformed, unknown, revoked, or expired.
- `403` — The API key lacks the required scope or Account entitlement.
- `404` — The requested resource does not exist or is not visible to this key.
- `429` — The API key or operation exceeded its rate limit.
- `500` — The server encountered an unexpected error.
- `503` — A required API dependency is temporarily unavailable.

## Changes

> 8 revisions in range; 2 could not be searched.

- **2026-08-08** `c57911e5fe90` — 21 warning
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `400`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `401`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `403`
  - added the new `audit_log_content_too_large` enum value to the `error/code` response property for the response status `404`
  - …17 more
- **2026-08-01** `d007d3f7173a` — 6 warning, 3 info
  - added the new `production_database_backup_storage` enum value to the `data/groups/items/metrics/items/id` response property for the response status `200`
  - added the new `production_database_backup_storage` enum value to the `data/metrics/items/id` response property for the response status `200`
  - added the new `production_database_logical_storage` enum value to the `data/groups/items/metrics/items/id` response property for the response status `200`
  - added the new `production_database_logical_storage` enum value to the `data/metrics/items/id` response property for the response status `200`
  - …5 more
- …earlier changes not shown

[Full history](https://skmtc.dev/replit/apis/replit-api/changes/usage/get.md)

---

[API](https://skmtc.dev/replit/apis/replit-api.md) · [All operations](https://skmtc.dev/replit/apis/replit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/replit/replit-api/revisions/7293f5108d59/schema)