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; 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 as Authorization: Bearer.
MCP tool: billing with action usage, and the same inputs
Scope: An access token needs billing:read.

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

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:

{
  "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,
    "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.

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.