# List a workspace's invoices

> A workspace's invoices, newest first.

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/workspaces/{workspace}/invoices</code></div>

`invoices` is every invoice billed to it (the plan, AI credit and usage), each with its `status`, `total_cents`, `currency` and links to view it and its PDF. `usage_invoices` are g1t's itemised invoices for usage, one when each month closes and one each time the card is charged near the limit, with their `lines` in millionths of a dollar; `amount_micros` is the usage, and the card processing fee (`fee_micros`) and tax (`tax_micros`) are on top. Prices exclude tax: Stripe adds it where it applies. `upcoming` is what the next invoice comes to so far. `unavailable` says why `invoices` could not be read just now, when it could not. Members of the workspace only.

`invoices` are in cents (`total_cents`); `usage_invoices` and `upcoming` in millionths of a dollar. A usage invoice's `reason` is `month` (the month closed) or `threshold` (charged near the limit), and its `status` `paid`, `open`, `failed` or `void`. An invoice's `status` is `paid`, `open`, `void`, `uncollectible` or `draft`.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`billing`](/reference/mcp/#billing) with `action` `invoices`, 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". |

## Example request

```sh
curl https://api.g1t.sh/workspaces/flagon-io/invoices \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "invoices": [
    {
      "id": "in_1Q2w3E4r5T6y7U8i",
      "number": "FLAGON-0004",
      "status": "paid",
      "total_cents": 4210,
      "currency": "usd",
      "created_at": "2026-10-01T00:05:00.000Z",
      "description": "Usage for 2026-09",
      "hosted_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i",
      "pdf_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i/pdf"
    }
  ],
  "usage_invoices": [
    {
      "id": "inv_01kkqz8d3c6f9t2wq5n8h1m4r7",
      "workspace": "flagon-io",
      "reason": "month",
      "period": "2026-09",
      "amount_micros": 42100000,
      "status": "paid",
      "hosted_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i",
      "pdf_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i/pdf",
      "lines": [
        {
          "description": "Agent: models",
          "amount_micros": 35900000
        },
        {
          "description": "Sandbox time",
          "amount_micros": 6200000
        }
      ],
      "created_at": "2026-10-01T00:05:00.000Z"
    },
    {
      "id": "inv_01kkqz8d3c6f9t2wq5n8h1m4r7",
      "workspace": "flagon-io",
      "reason": "month",
      "period": "2026-09",
      "amount_micros": 42100000,
      "status": "paid",
      "hosted_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i",
      "pdf_url": "https://invoice.example.com/i/acct_1/in_1Q2w3E4r5T6y7U8i/pdf",
      "lines": [
        {
          "description": "Agent: models",
          "amount_micros": 35900000
        },
        {
          "description": "Sandbox time",
          "amount_micros": 6200000
        }
      ],
      "created_at": "2026-10-01T00:05:00.000Z",
      "fee_micros": 1600000,
      "tax_micros": 3510000
    }
  ],
  "upcoming": {
    "closes_at": "2026-11-01T00:00:00.000Z",
    "subscriptions_micros": 20000000,
    "usage_micros": 10210000,
    "total_micros": 30210000
  },
  "unavailable": null
}
```

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