Get Consumption by API Key (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.

Attribute credit consumption to specific API keys with a per-tool breakdown. The primary use case is incident response: a key gets leaked, you rotate it, then you call this tool to understand exactly what was done with the key while it was active. Deleted/rotated keys appear with deleted: true so historical attribution is preserved.

Tool key: admin_get_consumption_by_api_key

Parameters

Name	Type	Required	Default	Description
`api_key_id`	string	No	–	Restrict to a single key. When omitted, all keys with attributed consumption in the window are returned.
`from`	ISO datetime	No	Org's billing-period start	Window start. Cannot be combined with `days`.
`to`	ISO datetime	No	Org's billing-period end	Window end. Cannot be combined with `days`.
`days`	int (1-366)	No	–	Lookback window in days. Cannot be combined with `from`/`to`.

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

Required Integrations

None.

Response

{
  "apiKeys": [
    {
      "apiKeyId": "qwhe1eobfnecz7rr5y9gtuyf",
      "apiKeyName": "ops-script",
      "apiKeyPrefix": "phx_10cc12a6",
      "creatorEmail": "alice@acme.com",
      "authMethod": "apikey",
      "oauthClientId": null,
      "oauthClientName": null,
      "deleted": false,
      "callCount": 96,
      "credits": 297,
      "byTool": [
        { "toolName": "company_install_time_series", "callCount": 21, "credits": 204 },
        { "toolName": "company_technographic", "callCount": 16, "credits": 32 },
        { "toolName": "company_spend", "callCount": 5, "credits": 15 }
      ]
    }
  ],
  "from": "2026-04-01T00:00:00.000Z",
  "to": "2026-05-01T00:00:00.000Z"
}

Field	Notes
`apiKeyName` / `apiKeyPrefix`	When the underlying `api_keys` row no longer exists, name falls back to `metadata.apiKeyName` captured at metering time, or `"Deleted API key"` when neither is available. Prefix is the 12-char display prefix.
`deleted`	`true` iff the LEFT JOIN against the live `api_keys` table missed — i.e. the key has been revoked or rotated. Historical consumption is still surfaced for audit.
`authMethod`	`"oauth"` for OAuth-issued tokens, `"apikey"` for explicit API keys, `"unknown"` for legacy rows that pre-date attribution metadata.
`callCount`	Billable calls (cache hits excluded), matching `admin_get_consumption`.
`credits`	Rounded to 6 decimals. Uses static credit cost per tool when set; falls back to `metadata.effectiveCreditCost` for dynamically-priced tools (e.g., `web_search`).

Unattributed rows excluded. tool_metering rows that lack a metadata.apiKeyId (legacy data, certain background jobs) cannot be placed under any key and are excluded from this response. Sum of per-key credits will be ≤ the org-wide admin_get_consumption total in orgs with such rows.

Use Cases

Leaked-key blast radius: rotate the key first; then call this tool with api_key_id to see exactly which tools were exercised during the window in which the key was exposed.
Per-key billing: for orgs that allocate spend back to internal cost centres via separate API keys, dump the response monthly.
Dormant-key detection: combined with admin_list_api_keys, confirm that a key flagged as dormant by lastUsedAt truly has zero consumption rather than just zero recent metering.

Example Usage

Last 30 days, all keys

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

Single key, explicit window

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "admin_get_consumption_by_api_key",
    "arguments": {
      "api_key_id": "qwhe1eobfnecz7rr5y9gtuyf",
      "from": "2026-04-01T00:00:00Z",
      "to": "2026-05-01T00:00:00Z"
    }
  }
}

How It Works

The org slug is derived from the API key. The implementation reuses the same JSONB extraction expressions as ConsumptionMonitoringService.getUsageByApiKey and the same per-tool credit accounting (computeMeteringCredits) as getPerUserConsumption so totals reconcile across the three admin consumption tools.

When api_key_id is provided, an existence probe runs against tool_metering.metadata (not api_keys) so a key that was deleted yesterday but used in the window still resolves. Cross-org isolation is automatic via executeInTenantSchema.

Each call writes an audit row with action view_consumption_by_api_key, metadata = { filter: { apiKeyId, from, to, days }, returnedCount }.

Error codes

Code	Trigger
`validation_error`	Args failed Zod validation, including the `days` ↔ `from`/`to` mutual exclusion and `from <= to` rule.
`range_too_large`	Resolved window exceeds 366 days.
`key_not_found`	`api_key_id` provided but no consumption is attributed to it in the caller's org. (A freshly created key with zero usage in the window also returns 404 here.)
`forbidden_admin_scope`	Key is user-scoped or the user is no longer an org admin.

Parameters​

Required Integrations​

Response​

Use Cases​

Example Usage​

Last 30 days, all keys​

Single key, explicit window​

How It Works​

Error codes​

See also​