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

> Spend limits, automatic refill settings, and spend alerts for a workspace.

Returns the workspace's effective spend limits, automatic refill settings, and spend alert state. Settings and alert spend cover the whole workspace.

Requires workspace Read. API keys can read only their bound workspace. No query parameters or pagination are supported. Alert spending includes excluded/deleted repositories and unattributed usage. Reading does not change settings, trigger alerts or refill credits.

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

An omitted limit means no limit is configured. A limit of `"0.00"` is a configured limit of zero.

**controls** `object`

**properties**

**allowOverages** `boolean`

Whether usage can continue past the available balance. Defaults to `false`.

**automaticRefillEnabled** `boolean`

Whether automatic refill is on. Defaults to `true`.

**refillAmount** `Money`

Amount added by each automatic refill. Defaults to USD 50.

**refillThreshold** `Money`

Balance that triggers an automatic refill. Defaults to USD 10.

**periodSpendLimit** `Money`

Workspace spend limit per billing period.

**reviewSpendLimit** `Money`

Spend limit per review. Defaults to USD 10.

**pullRequestSpendLimit** `Money`

Spend limit per pull request. Defaults to USD 50.

**checkRunPullRequestSpendLimit** `Money`

Check run agent spend limit per pull request. Defaults to USD 100.

**githubActionsWorkflowSpendLimit** `Money`

Spend limit per GitHub Actions workflow. Defaults to USD 100.

**cliReviewPeriodSpendLimit** `Money`

Workspace CLI review spend limit per billing period.

**cliReviewDefaultUserPeriodSpendLimit** `Money`

Default per-user CLI review spend limit per billing period. Per-user overrides are not returned.

**murmurPeriodSpendLimit** `Money`

Agent spend limit per billing period.

**spendAlerts** `SpendAlerts`

Monthly spend alerts. Omitted for non-credit plans or when disabled; omission does not mean zero spend.

**murmurSpendAlerts** `SpendAlerts`

Agent spend alerts. Omitted for non-credit plans or when disabled.

**readTime** `string`

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

### SpendAlerts

**periodStart** `string`

Start of the alert period (RFC 3339).

**periodEnd** `string`

End of the alert period (RFC 3339).

**currentSpend** `Money`

Workspace spend tracked for the alert period.

**thresholds** `object[]`

Configured thresholds, at most 20.

**properties**

**threshold** `Money`

Spend amount that triggers the alert.

**triggered** `boolean`

Whether the threshold has been reached.

**triggeredAt** `string`

When the threshold was reached (RFC 3339), when available.

### Money

**amount** `string`

Decimal amount in major units, e.g. `"50.00"`.

**currency** `string`

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

```bash cURL theme={null}
curl https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/billing/controls \
  -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/controls",
    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/controls",
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "controls": {
    "allowOverages": false,
    "automaticRefillEnabled": true,
    "refillAmount": {
      "amount": "50.00",
      "currency": "USD"
    },
    "refillThreshold": {
      "amount": "10.00",
      "currency": "USD"
    },
    "periodSpendLimit": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "reviewSpendLimit": {
      "amount": "10.00",
      "currency": "USD"
    },
    "pullRequestSpendLimit": {
      "amount": "50.00",
      "currency": "USD"
    },
    "checkRunPullRequestSpendLimit": {
      "amount": "100.00",
      "currency": "USD"
    },
    "githubActionsWorkflowSpendLimit": {
      "amount": "100.00",
      "currency": "USD"
    },
    "spendAlerts": {
      "periodStart": "2026-09-01T00:00:00Z",
      "periodEnd": "2026-10-01T00:00:00Z",
      "currentSpend": {
        "amount": "250.00",
        "currency": "USD"
      },
      "thresholds": [
        {
          "threshold": {
            "amount": "200.00",
            "currency": "USD"
          },
          "triggered": true,
          "triggeredAt": "2026-09-12T09:30:00Z"
        },
        {
          "threshold": {
            "amount": "500.00",
            "currency": "USD"
          },
          "triggered": false
        }
      ]
    }
  },
  "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.