---
title: "Get workspace credit usage"
method: GET
path: "/v1/workspaces/{workspace_id}/billing/credit-usage"
tags: ["billing-usage"]
---

# Get workspace credit usage

`GET /v1/workspaces/{workspace_id}/billing/credit-usage`

**Plan:** `Enterprise`

Returns credit usage for a time window: one aggregate row by default, per-member or per-project rows with group_by, or time-bucketed rows with interval. Member-attributed rows (group_by=member, or a query filtered to one user_id) also carry the member's display_name and workspace email; project rows carry the project ID only (join the projects endpoint for the name). Grouped rows cover only entities with usage in the window (zero-usage members are omitted), and usage not attributed to a member or project counts toward workspace_total but appears in no row. Queries not restricted to the calling user (user_id=me) require workspace admin permission.

## Path parameters

- `workspace_id` string, required — Workspace ID

## Query parameters

- `group_by` 'member' | 'project' — Group rows by member or project across the window. Omit for one workspace-wide aggregate row. Cannot be combined with interval.
- `interval` 'day' | 'week' | 'month' — Bucket rows by time. Coarser intervals allow a longer window (~400 days at day, ~3 years at week, ~10 years at month). Cannot be combined with group_by.
- `start_date` string, date, required — Required inclusive start (UTC day).
- `end_date` string, date — Inclusive end (UTC day). Defaults to today (UTC).
- `category` 'all' | 'build' | 'run' — Filter credits to All, Build, or Run.
- `project_id` string — Optional: restrict to a single project's usage.
- `user_id` string — Optional: restrict to a single member's usage. Pass 'me' for the calling user; queries not restricted to the caller require workspace admin permission.
- `limit` integer — Maximum number of items to return
- `cursor` string — Opaque pagination cursor returned by the previous page

## Response `200`

OK

- V1BillingUsageBody
  - `data` V1BillingUsageRow[], nullable, required
    - `build` number, double, required — Build-time credits.
    - `connectors` number, double, required — Connector credits, e.g. Google Maps requests.
    - `connectors_breakdown` V1WorkspaceUsageConnectorBreakdown[], nullable — Per-connector breakdown. Interval buckets only.
      - `credits` number, double, required — Credits attributed to this connector in the bucket.
      - `key` string, required — Stable connector key, e.g. google_maps.
      - `label` string, required — Display label for the connector.
    - `database` number, double, required — Database credits.
    - `database_breakdown` V1WorkspaceUsageDatabaseBreakdown[], nullable — Database server/storage breakdown. Interval buckets only.
      - `credits` number, double, required — Credits attributed to this database subcategory in the bucket.
      - `key` 'database_server' | 'database_storage', required — Stable database subcategory key.
      - `label` string, required — Display label for the database subcategory.
    - `display_name` string — Member display name. Present on member-attributed rows (group_by=member, or a query filtered to one user_id) when the caller also holds the members:read scope.
    - `email` string — Member email as stored on the workspace membership (not the user's primary/personal email). Present on member-attributed rows when the caller also holds the members:read scope.
    - `functions` number, double, required — Compute credits from functions and workers.
    - `gateway` number, double, required — AI Gateway credits.
    - `gateway_models` V1WorkspaceUsageGatewayModel[], nullable — Per-model AI Gateway breakdown. Interval buckets only.
      - `credits` number, double, required — Credits attributed to this model in the bucket.
      - `name` string, required — Model name.
      - `provider` string, required — Model provider, e.g. anthropic, openai.
    - `network` number, double, required — Network data-transfer credits.
    - `period_end` string — Inclusive row end (YYYY-MM-DD, UTC), clamped to the requested window at the edges.
    - `period_start` string — Inclusive row start (YYYY-MM-DD, UTC). Present on interval buckets and the aggregate row.
    - `project_id` string — Project this row aggregates (group_by=project). Join /v1/projects for the name.
    - `realtime` number, double, required — Realtime credits.
    - `run` number, double, required — Run-time credits (sum of the per-category fields below).
    - `storage` number, double, required — Storage credits.
    - `total` number, double, required — Total credits in this row.
    - `user_id` string — Member this row aggregates (group_by=member) or is filtered to (user_id).
  - `entity_count` integer — Number of grouped entities across all pages; group_by queries only.
  - `pagination` Pagination, required
    - `has_more` boolean, required — Whether more results are available beyond this page
    - `next_cursor` string, nullable, required — Cursor for the next page; null when there are no more results
  - `period` V1BillingUsagePeriod, required
    - `end` string, required — Inclusive end of the covered window (YYYY-MM-DD, UTC).
    - `group_by` string — Grouping dimension the rows use; group_by queries only.
    - `interval` string — Bucket size the rows use; interval queries only.
    - `start` string, required — Inclusive start of the covered window (YYYY-MM-DD, UTC).
  - `workspace_total` number, double, required — Total matching credits across the whole window — same on every page, not just this page's rows.

## Other responses

- `401` — Missing or invalid API key.
- `402` — This operation or requested configuration requires a workspace plan that includes this feature.
- `403` — The key or caller lacks the required scope or permission.
- `406` — The Accept header excludes every media type this endpoint produces.
- `429` — Too many requests. Retry after the interval in Retry-After when present.
- `default` — Error. The response body uses the standard error envelope; status matches the HTTP status code and type is a machine-readable error code.

---

[API](https://skmtc.net/lovable/apis/lovable-api.md) · [All operations](https://skmtc.net/lovable/apis/lovable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lovable/lovable-api/revisions/aa8d44585147/schema)