> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get billing balance

> Credit balance, usage, and amounts due for the current billing period.

Returns the workspace's credit balances and billed amounts for the current period. Amounts cover the whole workspace and are provisional.

Requires workspace Read. API keys can read only their bound workspace. No query parameters or pagination are supported. Excluded/deleted repositories and unattributed usage remain included.

Plan amounts and credit balances are not an atomic snapshot. An unavailable balance is not zero: check `balanceAvailable`, which is omitted when false. Failed plan/balance reads fail the request; unknown plan currency returns `400` (`FAILED_PRECONDITION`). This operation does not initiate payments.

## Authorization

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `string` *required*

Numeric GitHub ID of the organization or user.

## Response

**balance** `object`

**properties**

**periodStart** `string`

Start of the billing period (RFC 3339).

**periodEnd** `string`

End of the billing period (RFC 3339).

**balanceAvailable** `boolean`

`false` when balances could not be read. `availableBalance` and `ledgerBalance` are then omitted.

**availableBalance** `Money`

Credit available to spend.

**ledgerBalance** `Money`

Recorded credit balance.

**usageAmount** `Money`

Priced meter usage billed this period. Differs from the nominal cost reported by agent credit usage.

**overageAmount** `Money`

Usage beyond the plan's included amount.

**nextInvoiceAmountDue** `Money`

Amount due on the next invoice.

**seatAmount** `Money`

Seat charges this period.

**agentCreditGranted** `Money`

Agent credit included in the plan this period.

**agentCreditUsed** `Money`

Agent credit used this period.

**agentCreditBalance** `Money`

Agent credit remaining.

**amountStatus** `string`

Always `BILLING_AMOUNT_STATUS_PROVISIONAL`. Amounts can change, including for past periods.

**readTime** `string`

When the response was generated (RFC 3339). Not a data freshness timestamp.

### Money

An omitted Money object means no value, not zero.

**amount** `string`

Decimal amount in major units, e.g. `"120.50"`. Cent values retain two decimals; USD centimill values retain five. Preserve decimal precision.

**currency** `string`

ISO 4217 code, e.g. `"USD"`.

```bash cURL theme={null}
curl https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
    headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
)
print(r.json())
```

```javascript JavaScript theme={null}
const res = await fetch(
  "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/balance",
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "balance": {
    "periodStart": "2026-09-01T00:00:00Z",
    "periodEnd": "2026-10-01T00:00:00Z",
    "balanceAvailable": true,
    "availableBalance": {
      "amount": "120.50",
      "currency": "USD"
    },
    "ledgerBalance": {
      "amount": "500.00",
      "currency": "USD"
    },
    "usageAmount": {
      "amount": "379.50",
      "currency": "USD"
    },
    "overageAmount": {
      "amount": "0.00",
      "currency": "USD"
    },
    "nextInvoiceAmountDue": {
      "amount": "0.00",
      "currency": "USD"
    },
    "seatAmount": {
      "amount": "0.00",
      "currency": "USD"
    },
    "agentCreditGranted": {
      "amount": "10.00",
      "currency": "USD"
    },
    "agentCreditUsed": {
      "amount": "4.20",
      "currency": "USD"
    },
    "agentCreditBalance": {
      "amount": "5.80",
      "currency": "USD"
    },
    "amountStatus": "BILLING_AMOUNT_STATUS_PROVISIONAL"
  },
  "readTime": "2026-09-15T18:00:00Z"
}
```

```json 401 theme={null}
{ "code": 16, "message": "unauthenticated" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.