AI usage · Organization · API reference

GET/v1/ai/usage

Get the organization's AI usage and credit balance for a month

organizations.ai_usage.get

ReadIdempotentSince 2026-11-01

Returns how the organization used AI in a calendar month (year_month, YYYY-MM; default the current month): totals (calls, credits, tokens in and out, images, voice seconds and sessions), credits by category (chat, multimedia, voice), and the breakdown by agent, by person (team members, the CRM and Social Inbox AI Team seats, portal clients; names already resolved, each with its share of the credits), by model and by day. It also returns the credit balance of the pool the organization consumes from (balance.org_id and balance.paid_by say whose: an Account that does not pay for itself consumes its workspace's credits). Credits are spent in this order: first the month's credits, which renew with each billing cycle and do not carry over (the plan's, balance.base_plan_credits, plus those of the pool's AI tier if it has one: balance.plan_credits_included is their sum), then the pool's extra credits (balance.extra_credits), which are prepaid, do not expire and stop at a monthly cap set by the owner. For the current month the balance is live (the month's credits included, used and remaining; balance.tier, the AI tier that added credits this period and how many; balance.extra_credits, with what can be used now, the wallet balance, what this period used and the owner's monthly cap in credits; total remaining, which adds the usable extra credits; the renewal date and whether the plan follows the billing cycle or the calendar month); for a past month it is approximate (current plan, without the AI tier or extra credits) and balance.approximate is true. When balance.paid_by is workspace, balance.tier and balance.extra_credits are null: they belong to whoever pays. balance.pack_credits_remaining is deprecated: credit packs were retired on 2026-10-20 and it now carries the usable extra credits, so total_remaining is still plan_credits_remaining plus pack_credits_remaining (read balance.extra_credits instead). Read-only: it never initializes or resets the balance, and AI tiers and extra credits are bought, configured and topped up only in the app, by an owner or an admin (AI Agents > Usage). Usage is recorded under the organization whose credits pay for it, so an Account that consumes its workspace's credits shows its usage in the workspace. In agents, configured_model is the model the agent uses today; what was charged is in models. Credits charged without an agent appear as agent_id unknown ('Sin agente'); image models charge credits without a call, and totals.images counts only the images the tools record. Use organizations.ai_usage.months to know which months have data. Owners and admins of the organization or of its workspace only (403 role_required); 400 invalid_input for a malformed year_month.

Scope: organizations:read
Permission: View the module · Only owner, admin
MCP tool: organizations_ai_usage_getOn the full surface; on the compact one, mb_execute_operation with id: "organizations.ai_usage.get".

Declared cost: up to 200 reads and 0 writes per call (they count against the daily quota).

Parameters

year_monthstringqueryoptional

The month to read, YYYY-MM (UTC calendar month). Default: the current month.

Response

year_monthstring

The month (YYYY-MM).

is_current_monthboolean

True for the current month (its balance is live).

has_usageboolean

False when the organization recorded no AI usage that month.

totalsobject

The month's totals.

credits_by_categoryobject

Credits by category.

agentsarray<object>

By agent, most credits first.

peoplearray<object>

By person, most credits first.

modelsarray<object>

By charged model, most credits first.

dailyarray<object>

By day of the month.

balanceobject | null

The credit balance of the pool the organization consumes from; null when there is none.

Errors

role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Example

curl "https://api.mb-suite.com/v1/ai/usage" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/ai/usage" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/ai/usage/months

List the months with AI usage

organizations.ai_usage.months

ReadIdempotentSince 2026-11-01

Lists the calendar months (YYYY-MM, newest first, up to 120) that have AI usage recorded for the organization, to choose the year_month of organizations.ai_usage.get. An organization that never used AI returns an empty list. Owners and admins of the organization or of its workspace only (403 role_required).

Scope: organizations:read
Permission: View the module · Only owner, admin
MCP tool: organizations_ai_usage_monthsOn the full surface; on the compact one, mb_execute_operation with id: "organizations.ai_usage.months".

Declared cost: up to 120 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.