# Get a workspace's usage > A workspace's usage over a range of days, at price, and what paid for it.
GET/workspaces/{workspace}/usage
`from` and `until` are UTC days, `YYYY-MM-DD`, with `until` included and at most 400 days in all; left out, the current month so far. `products` narrows it to product families (agent, sandboxes, gateway, deployments, git_storage, packages, security, search) and `projects` to repositories ("owner/name"). Returns `totals`: `price_micros` less `discount_micros`, `included_micros` and `credits_micros` is `charged_micros`, what is left for the workspace to pay; `pending_micros` is metered this month and charged when it closes, counted in any range that reaches into the current month, and `pending_charged_micros` is what of it will be charged then, after the discount and what g1t covers; `cost_micros` is what it cost g1t. Then `days` (each day and product with usage), `products` (every family, with its meters: quantity, unit, amount, a `daily` amount for each day of the range, any `allowance`, the split `by_project`, and a `note` where the quantity needs one: the agent rate's meters, `agent_rate` and `agent_rate_own` (on the workspace's own model key), count weighted tokens and name the weights), `projects` (every repository with usage in the range), `models` (the agent's input, output, cache-read and cache-write tokens by model, most first), `by_agent` and `by_person` (the agent product at price by the agent that did the work, by handle, and by who asked, by username; `g1t` is g1t's own runs on repositories, an empty key is work attributed to no one; each sums to the agent product), and the AI credit and other credit left now. With `group_by` (`product`, `project` or `day`), `groups` adds up the range that way. Amounts are whole millionths of a dollar. Members of the workspace only. Every product family is listed, in order, even with nothing used; this example shows two. `daily` has one amount for each day of the range, oldest first. `projects` and `products` take several values separated by commas: `?products=agent,sandboxes`. A range of more than 400 days, or one that ends before it starts, is refused with `invalid`. - **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`. - **MCP tool:** [`billing`](/reference/mcp/#billing) with `action` `usage`, and the same inputs - **Scope:** An access token needs [`billing:read`](/guides/authentication/#scopes). ## Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `workspace` | string | Yes | The workspace's slug, e.g. "flagon-io". | ## Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `from` | string | No | The first day, YYYY-MM-DD (UTC). The first of this month if not given. | | `until` | string | No | The last day, included, YYYY-MM-DD (UTC). Today if not given. | | `products` | array of strings | No | Only these product families; all of them if not given. In a query string, separate them with commas. One of `agent`, `sandboxes`, `gateway`, `deployments`, `git_storage`, `packages`, `security`, `search`. | | `projects` | array of strings | No | Only these repositories, as "owner/name"; all of them if not given. In a query string, separate them with commas. | | `group_by` | string | No | Also add up the range by product, project or day, as `groups`. One of `product`, `project`, `day`. | ## Example request ```sh curl "https://api.g1t.sh/workspaces/flagon-io/usage?from=2026-10-01&until=2026-10-07&group_by=project" \ -H "Authorization: Bearer $G1T_TOKEN" ``` ## Example response A successful request answers `200` with: ```json { "from": "2026-10-01", "until": "2026-10-07", "totals": { "price_micros": 48210000, "discount_micros": 0, "included_micros": 20000000, "credits_micros": 18000000, "charged_micros": 10210000, "pending_micros": 1340000, "pending_charged_micros": 1340000, "cost_micros": 40100000 }, "days": [ { "day": "2026-10-06", "product": "agent", "micros": 12400000 }, { "day": "2026-10-06", "product": "sandboxes", "micros": 2100000 }, { "day": "2026-10-07", "product": "agent", "micros": 9800000 } ], "products": [ { "key": "agent", "label": "Agent", "micros": 41000000, "meters": [ { "key": "agent_models", "label": "Models", "product": "agent", "unit": "tokens", "quantity": 9120000, "micros": 41000000, "pending_micros": 0, "daily": [ 3100000, 5200000, 4400000, 6000000, 0, 12400000, 9800000 ], "allowance": null, "by_project": [ { "project": "flagon-io/g1t", "micros": 36000000, "quantity": 8010000 }, { "project": "flagon-io/hello", "micros": 5000000, "quantity": 1110000 } ] } ], "features": [ { "key": "runs", "label": "Runs", "micros": 33000000, "count": 14 }, { "key": "reviews", "label": "Reviews", "micros": 8000000, "count": 9 } ] }, { "key": "sandboxes", "label": "Sandboxes", "micros": 7210000, "meters": [ { "key": "sandbox", "label": "Sandbox time", "product": "sandboxes", "unit": "seconds", "quantity": 41300, "micros": 7210000, "pending_micros": 0, "daily": [ 900000, 1200000, 800000, 1100000, 0, 2100000, 1110000 ], "allowance": { "used": 41300, "of": 108000, "unit": "seconds" }, "by_project": [ { "project": "flagon-io/g1t", "micros": 7210000, "quantity": 41300 } ] } ], "features": [] } ], "projects": [ "flagon-io/g1t", "flagon-io/hello" ], "models": [ { "model": "claude-sonnet-5-5", "input": 310000, "output": 420000, "cache_read": 7800000, "cache_write": 590000 } ], "by_agent": [ { "key": "g1t", "label": "@g1t", "micros": 21400000, "count": 14 }, { "key": "mike", "label": "@mike", "micros": 800000, "count": 6 } ], "by_person": [ { "key": "chase", "label": "@chase", "micros": 21900000, "count": 19 }, { "key": "", "label": "No one asked", "micros": 300000, "count": 1 } ], "included": { "used": 20, "of": 20, "unit": "dollars" }, "discount_percent": null, "ai_credit_micros": 62000000, "credit_micros": 0, "trial_micros": null, "plan": "pro", "free": false, "group_by": "project", "groups": [ { "key": "flagon-io/g1t", "micros": 43210000 }, { "key": "flagon-io/hello", "micros": 5000000 } ] } ``` ## Errors A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors). | Status | Code | When | | --- | --- | --- | | 401 | `unauthenticated` | A token is required, or the one sent is not valid. | | 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. | | 404 | `not_found` | It does not exist, or you cannot see it. | | 422 | `invalid` | The input is not valid. `message` says which field and why. |