Get Consumption by API Key (Admin)

Per-key credit consumption with per-tool breakdown for the calling org. Includes deleted/rotated keys (with deleted: true) for historical attribution. Without api_key_id: all keys with attributed usage. Requires an admin-scoped API key.

Parameters

Name	Type	Default	Description
api_key_id	string	-	Filter to a single API key. When omitted, all keys with attributed usage in the window are returned.
from	string	-	ISO datetime; window start.
to	string	-	ISO datetime; window end.
days	integer	-	Window in days (1-366). Mutually exclusive with from/to.

Use Cases

• Which API key drove a sudden credit spike this week? — per-key attribution for incident response
• Attribute historical usage to a rotated or deleted key (returned with deleted: true)
• Which tools is a single API key spending credits on? — per-tool breakdown for one key

Example Usage

All keys with attributed usage over the last 7 days

{
  "tool": "admin_get_consumption_by_api_key",
  "arguments": {
    "days": 7
  }
}

Single key over an explicit window

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

Response Format

Field	Type	Description
apiKeys	array	Per-key consumption rows for the resolved window, sorted by credits desc.
apiKeys[].apiKeyId	string
apiKeys[].apiKeyName	string
apiKeys[].apiKeyPrefix	string
apiKeys[].creatorEmail	string | null
apiKeys[].authMethod	string
apiKeys[].oauthClientId	string | null
apiKeys[].oauthClientName	string | null
apiKeys[].deleted	boolean	True if the underlying api_keys row no longer exists (rotated/deleted). Historical consumption is preserved for audit.
apiKeys[].callCount	integer	Billable calls (excludes cache hits) within the window.
apiKeys[].credits	number
apiKeys[].byTool	array
apiKeys[].byTool[].toolName	string
apiKeys[].byTool[].callCount	integer
apiKeys[].byTool[].credits	number
from	string	Start of the consumption window (inclusive), ISO string.
to	string	End of the consumption window (exclusive), ISO string.