Skip to content
MCP Gateway

Read backend-owned usage rollups for one MCP server.

GET
/v1/mcp-servers/{server_id}/usage

Read-only V1 endpoint for the MCP server detail Usage tab. The backend derives rollups from metadata-only audit events and optional live manifest tool names; clients should not aggregate raw audit rows. Bucket widths are hourly for 24h, six-hour for 7d, and daily for 30d.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
server_id
required
string

Query Parameters

Section titled “Query Parameters ”
tenant_id
string
>= 1 characters

Defaults to the configured bootstrap tenant when omitted.

environment_id
string
>= 1 characters

Defaults to the configured bootstrap environment when omitted.

range
string
default: 24h
Allowed values: 24h 7d 30d

Usage lookback range. Defaults to 24h.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Metadata-only usage rollup with summary, timeseries, tools, consumers, and failure hotspots.

object
schema_version
required
server_id
required
string
>= 1 characters
environment_id
required
string
>= 1 characters
range
required
Allowed values: 24h 7d 30d
generated_at
required
string format: date-time
summary
required
object
total_calls
required
integer
successful_calls
required
integer
denied_calls
required
integer
failed_calls
required
integer
success_rate
required
number
<= 1
deny_rate
required
number
<= 1
error_rate
required
number
<= 1
p95_latency_ms
required
integer
unique_agents
required
integer
unique_users
required
integer
last_called_at
required
string format: date-time
nullable
timeseries
required
Array<object>
object
bucket_start
required
string format: date-time
total_calls
required
integer
successful_calls
required
integer
denied_calls
required
integer
failed_calls
required
integer
p95_latency_ms
required
integer
tool_usage
required
Array<object>
object
tool_id
required
string
>= 1 characters
name
required
string
>= 1 characters
calls
required
integer
success_rate
required
number
<= 1
deny_rate
required
number
<= 1
error_rate
required
number
<= 1
p95_latency_ms
required
integer
last_called_at
required
string format: date-time
nullable
top_consumers
required
object
agents
required
Array<object>
<= 10 items
object
agent_id
required
string
>= 1 characters
calls
required
integer
denied_calls
required
integer
failed_calls
required
integer
last_seen_at
required
string format: date-time
users
required
Array<object>
<= 10 items
object
user_id
required
string
>= 1 characters
calls
required
integer
denied_calls
required
integer
failed_calls
required
integer
last_seen_at
required
string format: date-time
client_surfaces
required
Array<object>
<= 10 items
object
client_surface_id
required
string
>= 1 characters
calls
required
integer
denied_calls
required
integer
failed_calls
required
integer
last_seen_at
required
string format: date-time
failure_hotspots
required
Array<object>
<= 10 items
object
type
required
Allowed values: policy credential route upstream
reason_code
required
string
/^[a-z0-9_]+$/
count
required
integer
last_seen_at
required
string format: date-time
permissions
required
object
resource_type
required
Allowed values: mcp_server agent credential_binding client_session
resource_id
required
string
>= 1 characters
allowed_actions
required
Array
Allowed values: mcp_server.read mcp_server.register mcp_server.submit_revision mcp_server.resubmit mcp_server.edit_owner mcp_server.validate_manifest mcp_server.reprobe mcp_server.approve_submission mcp_server.reject_submission mcp_server.disable mcp_server.deprecate mcp_server.archive mcp_server.compare_versions agent.read agent.submit agent.edit agent.approve agent.reject agent.disable agent.archive agent.revoke api_source.read api_source.import api_source.review api_source.approve api_source.reject api_source.disable api_source.archive credential_binding.read credential_binding.create credential_binding.update credential_binding.rotate credential_binding.disable credential_binding.revoke credential_binding.approve credential_binding.audit_read identity_provider.read identity_provider.diagnose role_binding.read role_binding.manage local_identity.read local_identity.manage reason_code.read reason_code.manage approval_queue.read approval_queue.batch_approve

400

Section titled “400 ”

Range is not one of 24h

403

Section titled “403 ”

Actor lacks mcp_server.read for this server scope.

404

Section titled “404 ”

MCP server registry record was not found.

Type set in Geist, Source Serif 4, and Departure Mono.