# get_workspace_spending

Source: https://modulify.ai/docs/api/workspaces/get-workspace-spending

Reads the monthly spending caps of a workspace, what this month's spending counts against them, the spending alerts and the auto top-up settings.

- Title: Read the spending caps, alerts and auto top-up
- Scope: `workspaces:read`
- Access: Read only
- Endpoint: `POST /v1/get_workspace_spending`

This is what **Spending** > **Settings** shows. Any member of the workspace can read it, and only the workspace owner can change it.

`caps` holds the monthly caps in credits, each null when it is not set:

- `total` caps everything the workspace spends: chat, images, videos, AI and extra emails.
- `ai` caps the AI that every site's server code calls, all sites together.
- `emails` caps the blocks of extra emails sites buy past their monthly allowance, all sites together.

`spent` is this month's spending counted against each cap, with refunds taken off. Once a cap is reached, that spending stops until the 1st of next month, in UTC, or until the cap is raised: chat refuses new turns, images and videos, AI pauses on every site and sites stop buying extra emails. A chat turn that is already running finishes. `period` is the month as `YYYY-MM` and `resetsAt` when it ends. `balance` is the credits left in the workspace.

`alerts` carries the emails the owner gets: `percents`, the points of each cap and of the budget that send one (any of 50, 75 and 90, and a cap always sends one when it is reached), `budget`, a monthly amount that only sends emails and stops nothing, and `lowBalance`, the balance under which the owner hears about it once. Each is null when it is off.

`autoTopUp` says whether credits are bought on their own: `enabled`, `threshold`, the balance under which a top-up runs, `credits`, the package each top-up buys, at `rate` per credit in `currency`, `maxPerMonth`, the most top-ups in a calendar month, `usedThisMonth`, `lastAt`, and `stoppedReason` with `stoppedMessage` once it turned itself off, for example after the card was declined. `card` holds the brand and the last 4 digits of the owner's card, and is only filled for the owner. `canManage` says whether the connected account may change these settings. See [Spending caps and alerts](https://modulify.ai/docs/plans/spending).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/get_workspace_spending`, sending the inputs below as a JSON object. The token needs the `workspaces:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/get_workspace_spending \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID"}'
```

Over MCP, the same method is the [get_workspace_spending tool](https://modulify.ai/docs/mcp/workspaces/get-workspace-spending).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace id. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.