---
title: "Tool gateway calls"
method: GET
path: "/client/usage/tools"
tags: ["Usage"]
---

# Tool gateway calls

`GET /client/usage/tools`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/usage/tools`
- Auth: HTTP bearer

Calls your agents made through the tool gateway: per tool, failures (`errors`) apart from calls a rule stopped (`stopped` — approvals, limits, the guardrail), every code seen, what the guardrail masked or stopped, latency, which key calls which tool, and `series` — calls per hour (per day past two days) for a timeline. These are NOT in `GET /client/usage`, whose figures are model calls only. No cost — gateway tool calls are free. (A model’s own built-in web search is billed per search and appears in `GET /client/usage` instead.) Optional `from`/`to` and `keyId`. Requires `usage:read`.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `keyId` string, uuid

## Response `200`

Tool call figures

- ToolUsageReport
  - `summary` ToolUsageSummary, required
    - `calls` integer, required
    - `errors` integer, required: Calls that FAILED — the tool, its server or we broke (including `tool_error`, an HTTP 200), or no such tool. Since 2026-09-27 this no longer includes calls a rule stopped (`stopped`) or whose answer the guardrail withheld (`withheld`); a monitor on `errors` that expected those should add them
    - `stopped` integer, required: Calls a rule stopped before they reached the tool — waiting for or declined an approval, over a limit, too many at once, or the guardrail refusing the arguments. Not failures
    - `withheld` integer, required: Calls whose tool ran and whose answer the guardrail withheld — a change may have happened. Not failures
    - `redacted` integer, required: Calls whose arguments or result the guardrail masked
    - `blocked` integer, required: Calls the guardrail blocked: arguments refused (in `stopped`) or answer withheld (`withheld`)
    - `avgLatencyMs` integer, nullable, required: Over calls that reached a tool; null when none did
    - `p95LatencyMs` integer, nullable, required: Over calls that reached a tool; null when none did
  - `series` object[], required: Calls per hour (per day past two days), oldest first; an hour with no calls is absent
    - `bucket` string, date-time, required
    - `calls` integer, required
    - `errors` integer, required
    - `stopped` integer, required
  - `byTool` object[], required
    - `endpoint` string, required: `mcp:<server>/<tool>`, or `mcp:gateway` for a name that matched no tool
    - `tool` string, nullable, required: `<server>/<tool>`; null for the `mcp:gateway` bucket
    - `calls` integer, required
    - `errors` integer, required
    - `stopped` integer, required
    - `withheld` integer, required
    - `redacted` integer, required
    - `blocked` integer, required
    - `avgLatencyMs` integer, nullable, required
    - `p95LatencyMs` integer, nullable, required
    - `lastCalledAt` string, date-time, required
  - `byError` object[], required
    - `code` 'unknown_tool' | 'rate_limited' | 'concurrency' | 'guardrail_blocked' | 'guardrail_args_blocked' | 'upstream_error' | 'tool_error' | 'internal_error' | 'approval_pending' | 'approval_denied' | 'grant_limit', required
    - `calls` integer, required: Rows, not refusals: repeated refusals are logged once per minute per key
  - `byKey` object[], required: Which key, filed under which project, called which tool
    - `apiKeyId` string, uuid, nullable, required: Null once the key is deleted
    - `keyName` string, nullable, required
    - `projectId` string, uuid, nullable, required
    - `projectName` string, nullable, required
    - `endpoint` string, required
    - `tool` string, nullable, required
    - `calls` integer, required
    - `errors` integer, required
    - `stopped` integer, required

## Other responses

- `403`: Key lacks usage:read

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)