# get_workspace_credit_usage

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

Reads what a workspace spent its credits on over a period, so you can see where they went rather than only how many are left.

- Title: Read where the credits went
- Scope: `workspaces:read`
- Access: Read only
- Endpoint: `POST /v1/get_workspace_credit_usage`

These are the figures the **Usage** tab of the Plans page shows. `total` is the credits spent in the window after refunds, and `refunded` is what came back for work that did not deliver. Credits added to the workspace, from the plan allowance, top ups or rewards, are not in it.

`categories` splits the spend into `building` (chat turns that build or edit a site), `images` (generated and edited images), `videos` (animated clips), `emails` (the blocks of extra sends a site bought past its included emails) and `other` (older one-off charges), each with its own `credits` and `refunded`. `sites` ranks every site that spent anything by its credits, with `deleted` true for a site that no longer exists and a null `projectId` for spend not tied to a site.

`usage` is the same spend over time in UTC, one entry per hour, day or month as `interval` says, each with its own `categories`. `days` and `since` say how long the window is and where it starts.

The window is a `period`, with the same choices as the date pickers in Modulify and `7d` when you send nothing, or a custom range from `from` to `to` of at most 3,660 days. Sending a `period` together with dates, or only one of the two dates, is refused. `get_workspace_credits` gives the balance itself, and `list_workspace_credit_activity` lists the individual charges behind these totals. See [Credits](https://modulify.ai/docs/plans/credits#see-where-your-credits-went).

## Request

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

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

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace id. |
| `period` | string | No | `day` (today so far, from midnight UTC), `24h` (the current hour and the 23 before it), `7d`, `30d` or `90d` (the last 7, 30 or 90 days counting today), `12mo` (this month and the 11 before it) or `all` (back to the first charge). Defaults to `7d`. Leave it out when sending `from` and `to`. |
| `from` | string | No | The first day of a custom range as `YYYY-MM-DD` in UTC. Send it together with `to`. |
| `to` | string | No | The last day of a custom range as `YYYY-MM-DD` in UTC, included in the range. Send it together with `from`. |

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