Get Consumption (Admin)

Read consumption (credits + tool calls) for the calling org. Without user_id: org-wide ConsumptionStatus. With user_id: per-user breakdown. Requires an admin-scoped API key.

Parameters

Name	Type	Default	Description
user_id	string	-	Optional UUID of a user. If provided, returns a per-user breakdown for that user. If omitted, returns the org-wide consumption status.
from	string	-	ISO datetime; window start (default: org's current billing period start).
to	string	-	ISO datetime; window end (default: org's current billing period end).

Use Cases

• How many credits has the org used this billing period, and how many remain?
• Is the org over its plan limit and in hard-enforcement mode?
• Break down a specific user's credit and tool-call usage over a date window

Example Usage

Org-wide consumption for the current billing period

{
  "tool": "admin_get_consumption",
  "arguments": {}
}

Per-user breakdown over an explicit window

{
  "tool": "admin_get_consumption",
  "arguments": {
    "user_id": "3f7c2b1a-9d4e-4c2a-8b1f-0a1b2c3d4e5f",
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-27T00:00:00Z"
  }
}

Response Format

Field	Type	Description
kind	string	Which variant this response is. org_wide (no user_id) populates status; per_user (user_id given) populates users, from, and to.
status	object	Org-wide ConsumptionStatus (same shape as the webapp consumption view). Present only when kind='org_wide'.
status.organizationSlug	string
status.organizationName	string
status.planId	string | null
status.planName	string | null
status.billingPeriod	object | null
status.credits	object
status.credits.used	number
status.credits.limit	number
status.credits.remaining	number
status.credits.percentUsed	number
status.overage	object
status.overage.amount	number	Overage credits beyond the plan limit.
status.overage.cost	number	Overage cost in cents.
status.enforcementMode	string
status.isOverLimit	boolean
status.isCustomPricing	boolean
users	array	Per-user credit and tool-call breakdown. Present only when kind='per_user'.
users[].userId	string
users[].email	string
users[].name	string | null
users[].callCount	number
users[].credits	number
users[].byTool	array
users[].byTool[].toolName	string
users[].byTool[].callCount	number
users[].byTool[].credits	number
from	string	Resolved window start (kind='per_user' only).
to	string	Resolved window end (kind='per_user' only).