Skip to main content
Glama
Sign In

Proof Holdings

by holdings.proof
OverviewDiscussionsAdmin

get_api_key_usage

Read-only

Get per-API-key usage for a given key id: verification counts by type/channel/status, plus verification-request/confirmation/authorization totals, and attribution context (attribution_cutoff_at, attributed_fraction). The counts cover the key and every key it replaced (api_key.replaced_key_ids). Counts only — no recipient identifiers. Scoped to the authenticated account; an API-key caller may read only its own key.

ACCESS: needs a Proof account. Authenticate this client (Claude Code: /mcp → Authenticate), or sign in with start_login — a session opens this tool — then call this tool again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

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

Input Schema

NameRequiredDescriptionDefault
idYesThe API key id to fetch usage for
environmentNoScope metrics to test or production data (default: production)

Output Schema

NameRequiredDescriptionDefault
api_keyYes
confirmationsYes
verificationsYes
authorizationsYes
attributed_fractionYesFraction of the user verifications linked to any API key in scope (null when there are none)
attribution_cutoff_atYesUTC-day-floored date attribution began for this user (earliest key-linked verification), or null
verification_requestsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "description": "Per-API-key usage: verification counts by type/channel/status + per-collection totals (requests, confirmations, authorizations) + attribution metadata. The counts cover the key and every key it replaced (`api_key.replaced_key_ids`). Counts only — no recipient identifiers (SEC-001). Data is returned for revoked keys (audit).",
+  "properties": {
+    "api_key": {
+      "additionalProperties": {},
+      "properties": {
+        "created_at": {
+          "type": "string"
+        },
+        "environment": {
+          "type": "string"
+        },
+        "expires_at": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "key_prefix": {
+          "type": "string"
+        },
+        "last_used_at": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        },
+        "profile_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "replaced_key_ids": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "revoked_at": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "scopes": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "key_prefix",
+        "environment",
+        "scopes",
+        "last_used_at",
+        "expires_at",
+        "revoked_at",
+        "created_at"
+      ],
+      "type": "object"
+    },
+    "attributed_fraction": {
+      "description": "Fraction of the user verifications linked to any API key in scope (null when there are none)",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "attribution_cutoff_at": {
+      "description": "UTC-day-floored date attribution began for this user (earliest key-linked verification), or null",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "authorizations": {
+      "additionalProperties": {},
+      "properties": {
+        "by_status": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "total",
+        "by_status"
+      ],
+      "type": "object"
+    },
+    "confirmations": {
+      "additionalProperties": {},
+      "properties": {
+        "by_status": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "total",
+        "by_status"
+      ],
+      "type": "object"
+    },
+    "verification_requests": {
+      "additionalProperties": {},
+      "properties": {
+        "by_status": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "total",
+        "by_status"
+      ],
+      "type": "object"
+    },
+    "verifications": {
+      "additionalProperties": {},
+      "properties": {
+        "by_channel": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "by_status": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "by_type": {
+          "additionalProperties": {
+            "type": "number"
+          },
+          "properties": {},
+          "type": "object"
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "total",
+        "by_type",
+        "by_channel",
+        "by_status"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "api_key",
+    "verifications",
+    "verification_requests",
+    "confirmations",
+    "authorizations",
+    "attribution_cutoff_at",
+    "attributed_fraction"
+  ],
+  "type": "object"
+}
  2. Changed1 schema field changed
    • removedInput schema / additionalProperties
      Removed value: -false
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=true; the description adds non-obvious behavior: counts are aggregated across the key plus every key it replaced, results contain no recipient identifiers, and access is scoped to the authenticated account with API-key callers limited to their own key. The prerequisite/auth flow is spelled out as well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and return contents are front-loaded in the first sentence, with aggregation semantics second and access prerequisites last. The first sentence is dense with field lists, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only lookup with a full output schema and complete parameter descriptions, the description covers everything left: what is counted, aggregation across replaced keys, privacy limits, tenant scoping, and the authentication prerequisite.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both `id` and the `environment` enum are already documented. The description clarifies that the id is a key id whose replaced keys are also included, but says nothing about the production/test scoping of `environment` beyond what the schema already states — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get per-API-key usage for a given key id') and then enumerates exactly what is returned: verification counts by type/channel/status, request/confirmation/authorization totals, and attribution fields. It also disambiguates scope ('counts cover the key and every key it replaced'), which separates it from a plain account-level usage read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: requires a Proof account, names the auth path (/mcp Authenticate or start_login), and constrains API-key callers to their own key. It does not explicitly name alternatives such as get_usage or list_api_keys, so the agent must infer which to pick when it wants account-wide versus per-key numbers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Proof Holdings toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources