> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abundly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage for one tool

> How often the agent called one specific tool, across chats and trigger runs, plus the most recent call inputs. `:toolName` is a tool name (lowercase with underscores, e.g. `send_email`), not a capability name — an unknown name returns 404 rather than a zero count.



## OpenAPI

````yaml /api-reference/workspace-api.json get /workspaceapi/agents/{agentId}/tool-usage/{toolName}
openapi: 3.1.0
info:
  title: Abundly Workspace API
  description: >-
    Read-only access to workspace-level and per-agent data. Every endpoint is a
    GET authenticated with a workspace API key (wk_) that has the Workspace read
    API scope.


    Private agents are listed by /workspaceapi/agents but return 403 on every
    per-agent endpoint, so enumerate from
    /workspaceapi/agents?includeOverview=true rather than iterating agent ids.
  version: 1.0.0
servers:
  - url: https://service.abundly.ai
    description: Shared platform
  - url: https://{tenant}.service.abundly.ai
    description: Dedicated deployment
    variables:
      tenant:
        default: your-tenant
security:
  - workspaceApiKey: []
paths:
  /workspaceapi/agents/{agentId}/tool-usage/{toolName}:
    get:
      summary: Get usage for one tool
      description: >-
        How often the agent called one specific tool, across chats and trigger
        runs, plus the most recent call inputs. `:toolName` is a tool name
        (lowercase with underscores, e.g. `send_email`), not a capability name —
        an unknown name returns 404 rather than a zero count.
      operationId: agents-agentId-tool-usage-toolName
      parameters:
        - name: agentId
          in: path
          required: true
          description: The agent id.
          schema:
            type: string
        - name: toolName
          in: path
          required: true
          description: >-
            The tool name to look up (e.g. 'get_skills', 'send_email',
            'http_request').
          schema:
            type: string
        - name: since
          in: query
          required: false
          description: >-
            ISO date string. Only count usage after this timestamp. Defaults to
            30 days ago.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Max recent calls to return (default 10).
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Success. Empty result sets are also 200.
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Response fields for this endpoint are not modelled in the spec
                  yet. See the Workspace API guide for the shapes.
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: >-
        Error. Every failure on this API returns JSON with a single `error`
        field.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                description: >-
                  Human-readable message. Every error on this API uses this
                  shape.
                type: string
            required:
              - error
            additionalProperties: false
  securitySchemes:
    workspaceApiKey:
      type: http
      scheme: bearer
      description: Workspace API key (wk_) with the Workspace read API scope enabled.

````