# get_workspace_credits

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

Reads the reconciled AI credit balance of a workspace, the figure to trust right after a renewal or a top up.

- Title: Read the AI credit balance
- Scope: `workspaces:read`
- Access: Read only
- Endpoint: `POST /v1/get_workspace_credits`

AI credits are what site generation spends. `get_workspace` also carries a balance, but that one is the stored figure and can be stale right after a renewal or a top up, so use this tool when the number has to be right.

Before answering, it applies any monthly reset or allowance change that is due. The answer is the buckets in `AiCredits`, so the balance is `SubscriptionLimit` minus `SubscriptionUsage` plus `TopUpCredits`, and `SubscriptionResetAt` is the date of the next monthly reset, null on the Free plan. See [Credits](https://modulify.ai/docs/plans/credits#what-a-balance-is-made-of).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/get_workspace_credits`, 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_credits \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID"}'
```

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

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