Skip to main content
GET
Count Platform API and MCP usage by tool or route and outcome: ok, denied, client and server errors
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/usage/summary reads the API’s request counts for an inclusive range of UTC days. It requires the platform:read permission, and the credential’s scopes must reach it. An External App is refused with 403.

Parameters

  • fromDay and toDay (required) are YYYY-MM-DD UTC days, inclusive. The range is at most 31 days, and toDay may not be before fromDay.
  • groupBy is tool (the default) or route. tool groups by the MCP tool that made the request, with none for a request that did not come from Forge MCP and other for one whose tool header was not a tool name. The tool name is the one the caller’s MCP server sent, so treat it as reported, not proven. route groups by the declared route, such as GET /api/v2/runs/list.
A malformed day, an inverted or over-long range, or another groupBy value answers 400 with the parameter named. So does a range holding more counter rows than one summary folds: narrow the range.

Response

data has fromDay, toDay, groupBy, counts and groups. counts is always door_b_requests. Each group has a key and the counts total, ok, denied, clientError and serverError, and groups are ordered by total, most used first.
  • What is counted. Each /api/v2/* request is one count. A tool call that fails inside Forge MCP before calling the API is not counted, and a tool that makes several requests counts each one.
  • A day late. Counts are folded overnight, so today’s requests are not in the answer yet. Counts are kept for 90 days.
  • No identities. The answer has no key, app, person or actor kind, and no MCP client name.

From MCP

Forge MCP exposes the summary as the resource template forge://usage/summary/{fromDay}/{toDay}, grouped by tool, when the budgets tool group is enabled. The route is also reachable through forge_call_operation with the operation getUsageSummary.

Authorizations

Authorization
string
header
required

A platform API key, created in the Console under Developers. Pass as Authorization: Bearer <key>. It acts as itself, under its role grants narrowed by its scopes.

Query Parameters

fromDay
string<date>
required
toDay
string<date>
required
groupBy
enum<string>
default:tool
Available options:
tool,
route

Response

The range's counts, most used first

data
object
required

Platform API request counts of a day range by MCP tool or route, and by outcome. Counts are Platform API requests (a tool that fails inside forge-mcp before calling the Platform API is not counted) and are a day late. No actor or caller-supplied client text.

meta
object
required