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

# Tool gateway call log

`GET /client/usage/tools/calls`

## Request

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

One row per tool call, newest first: which tool, which key, status, latency, guardrail outcome and error code. **Never the arguments or the result** — they are not stored. `band` is `errors` (failed calls — since 2026-09-27 NOT the calls a rule stopped or whose answer the guardrail withheld), `stopped` (calls a rule stopped before the tool: approval, a limit, the guardrail on the arguments) or `guardrail`; `endpoint` narrows to one tool (`mcp:<server>/<tool>`). Keyset-paginated: pass the previous response's `nextCursor` as `cursor`. Requires `usage:read`.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `keyId` string, uuid
- `band` 'all' | 'errors' | 'stopped' | 'guardrail'
- `endpoint` string
- `limit` integer
- `cursor` string

## Response `200`

Tool calls, newest first

- ToolCallPage
  - `data` ToolCallRow[], required
    - `id` integer, required
    - `apiKeyId` string, uuid, nullable, required
    - `endpoint` string, required
    - `tool` string, nullable, required
    - `status` integer, required
    - `latencyMs` integer, required
    - `guardrailAction` 'redact' | 'block', nullable, required
    - `errorCode` 'unknown_tool' | 'rate_limited' | 'concurrency' | 'guardrail_blocked' | 'guardrail_args_blocked' | 'upstream_error' | 'tool_error' | 'internal_error' | 'approval_pending' | 'approval_denied' | 'grant_limit', nullable, required
    - `requestId` string, nullable, required
    - `createdAt` string, date-time, required
  - `nextCursor` string, nullable, required: Pass back as `cursor` for the next page; null on the last

## 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)