Plutus

query_usage

Read-onlyIdempotent

Query time-bucketed usage telemetry this account's own backend has pushed or synced in (e.g. API request counts, tokens processed) — the raw data unit-economics metrics divide cost by (see list_unit_metrics/query_unit_costs), inspected directly rather than through a pre-defined ratio. quantity is a raw count with no currency — never treat it as money. Optionally broken down by external_customer_id when the pushed rows carry one. Mirrors GET /api/usage.

Input Schema

Name	Required	Description
`end_date`	No	ISO-8601 end of the date range (exclusive)
`group_by`	No	Time bucket size (default: day). "hour" is only supported for ranges of 7 days or less.
`start_date`	No	ISO-8601 start of the date range (inclusive)
`breakdown_by`	No	"external_customer_id", or "dimension:<key>" to group by a key of the pushed dimensions map (e.g. "dimension:feature"; list the keys with list_usage_dimensions dimension "dimension_key"). Rows keep the external_customer_id field name; at most 50 values are returned, the rest folded into "Other".
`filter_metric`	No	Restrict to these metric names
`exclude_metric`	No	Leave out these metric names
`filter_category`	No	Restrict to usage from sources in these categories (see query_costs for the list; customer-defined push sources count as "custom")
`exclude_category`	No	Leave out usage from sources in these categories
`filter_source_id`	No	Restrict to usage pushed/synced under these usage-source ids
`exclude_source_id`	No	Leave out usage under these usage-source ids
`filter_external_customer_id`	No
`exclude_external_customer_id`	No	Leave out these customers

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 26, 2026

addedInput schema / properties / breakdown_by / description

Added value: +"\"external_customer_id\", or \"dimension:<key>\" to group by a key of the pushed dimensions map (e.g. \"dimension:feature\"; list the keys with list_usage_dimensions dimension \"dimension_key\"). Rows keep the external_customer_id field name; at most 50 values are returned, the rest folded into \"Other\"."

removedInput schema / properties / breakdown_by / enum
```
Removed value: -[
-  "external_customer_id"
-]
```

addedInput schema / properties / breakdown_by / pattern

Added value: +"^(external_customer_id|dimension:[A-Za-z0-9_.-]{1,64})$"

Changed5 schema fields changedOct 23, 2026

addedInput schema / properties / exclude_category

Added value: +{
+  "description": "Leave out usage from sources in these categories",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_external_customer_id

Added value: +{
+  "description": "Leave out these customers",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_metric

Added value: +{
+  "description": "Leave out these metric names",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / exclude_source_id

Added value: +{
+  "description": "Leave out usage under these usage-source ids",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / filter_category

Added value: +{
+  "description": "Restrict to usage from sources in these categories (see query_costs for the list; customer-defined push sources count as \"custom\")",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedSep 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

It adds critical behavioral traits beyond the annotations, specifically the warning: 'quantity is a raw count with no currency — never treat it as money.' This is crucial operational context for the AI agent interpreting the returned data.

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?

The description is dense but efficient. It front-loads the primary function, followed by technical details, the vital currency warning, and the scope, making every sentence serve a structural purpose.

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?

Given the high parameter count (12) and schema coverage, the description successfully handles the contextual 'why' and 'how to interpret' the results. It covers the units, the data source, and critical limitations, making it highly complete for this complexity.

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

Parameters4/5

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

Although schema coverage is high, the description adds vital semantic meaning, such as explaining that the metrics are for 'unit-economics divide cost by' and detailing the breakdown constraint ('at most 50 values are returned, the rest folded into "Other"').

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?

The purpose is extremely clear: 'Query time-bucketed usage telemetry.' It specifies the type of data (raw metrics like API counts, tokens processed) and explicitly differentiates itself by stating it provides raw unit-economics metrics, distinct from pre-defined ratios.

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?

The description provides strong guidance on *how* to use the data by advising the agent to inspect raw units directly rather than using cost ratios. It also notes an optional breakdown by external_customer_id when applicable.

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

All Plutus tools Inspect

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

Need Help?