Get Consumption (admin)

Requires admin-scoped API key

This tool is only available when authenticated with an admin-scoped Phoenix API key. User-scoped keys never see it in tools/list and receive 403 forbidden_admin_scope if they try to call it directly. See Admin operations overview for details.

Read consumption for the calling org. Without user_id, returns the same ConsumptionStatus shape the webapp UI displays. With user_id, returns a per-user breakdown including per-tool call counts and credit spend.

Tool key: admin_get_consumption

Parameters

Name	Type	Required	Default	Description
`user_id`	UUID	No	–	If provided, returns a per-user breakdown for that user. Otherwise returns the org-wide consumption status.
`from`	ISO datetime	No	Org's current billing period start	Window start.
`to`	ISO datetime	No	Org's current billing period end	Window end.

The [from, to] window must not exceed 366 days.

Required Integrations

None.

How It Works

The org slug is derived from the API key.

Without user_id: delegates to ConsumptionMonitoringService.getConsumptionStatus(slug). Returns the same shape as the webapp consumption view.
With user_id: confirms the user has an active membership in the caller's org (otherwise returns user_not_found), then aggregates tool_metering rows in the tenant schema grouped by (user_id, tool_name). Cache hits are excluded from billable counts. After the tenant query commits, user emails and names are fetched from public.users via a single inArray lookup. No cross-schema joins.

Each call writes an audit row with action view_consumption, metadata = { from, to, scope: "org" | "user" }. Consumption data can be sensitive in some accounts, which is why reads are audited.

Use Cases

Daily cron to dump org-wide credit usage into Snowflake or BigQuery.
Per-user reports for managers tracking AI tool adoption.
Anomaly detection — flag users whose call counts spike outside their norm.

Example Usage

Org-wide

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "admin_get_consumption",
    "arguments": {}
  }
}

Response:

{
  "organizationSlug": "acme",
  "organizationName": "Acme",
  "planId": "plan_growth",
  "planName": "Growth",
  "billingPeriod": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-04-30T23:59:59.000Z"
  },
  "credits": {
    "used": 1234.5,
    "limit": 10000,
    "remaining": 8765.5,
    "percentUsed": 12.35
  },
  "overage": { "amount": 0, "cost": 0 },
  "enforcementMode": "soft",
  "isOverLimit": false,
  "isCustomPricing": false
}

Per-user (last 7 days)

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "admin_get_consumption",
    "arguments": {
      "user_id": "9a3a9b40-3a6f-4f0a-9f8e-1b7f0b2c0d10",
      "from": "2026-04-22T00:00:00Z",
      "to": "2026-04-29T00:00:00Z"
    }
  }
}

Response:

{
  "users": [
    {
      "userId": "9a3a9b40-3a6f-4f0a-9f8e-1b7f0b2c0d10",
      "email": "alice@acme.com",
      "name": "Alice",
      "callCount": 42,
      "credits": 87.5,
      "byTool": [
        { "toolName": "company_firmographic", "callCount": 30, "credits": 30 },
        { "toolName": "company_spend", "callCount": 12, "credits": 36 }
      ]
    }
  ],
  "from": "2026-04-22T00:00:00.000Z",
  "to": "2026-04-29T00:00:00.000Z"
}

Error codes

Code	Trigger
`invalid_request`	Args failed Zod validation.
`invalid_range`	`from > to`.
`range_too_large`	Window exceeds 366 days.
`user_not_found`	`user_id` provided but not an active member of this org.
`forbidden_admin_scope`	Key is user-scoped or the user is no longer an org admin.

Parameters​

Required Integrations​

How It Works​

Use Cases​

Example Usage​

Org-wide​

Per-user (last 7 days)​

Error codes​

See also​