Read where the credits went

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.

POST /v1/get_workspace_credit_usageScopeworkspaces:readRead only

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.

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.

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.

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 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 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 explains every status code a call can answer with.