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

# Get Devin Agent Tool Calls

> Count agent tool calls, such as web search or run command, made by your team in Devin Desktop and the Devin CLI, grouped by tool, user, model, IDE, or OS.

<Note>
  This is a **v2 endpoint** that uses Bearer token authentication and query parameters, unlike the v1 Analytics API which uses service keys in the request body. See [Authentication](#authentication) below.
</Note>

<Warning>
  This endpoint is **not** intended for real-time usage monitoring. The rate limit is low
  (10 requests per hour per team). Use it for periodic reporting and bulk export.
</Warning>

## Authentication

This endpoint uses **Bearer token** authentication. Include your token in the `Authorization` header:

```
Authorization: Bearer <your_token>
```

Use either a Devin service user API key with the **Use Local Analytics API** permission or a Windsurf
service key with the **Analytics Read** permission. See
[Authentication](/desktop/accounts/api-reference/analytics-v2-introduction#authentication) for how to
create each one.

Unlike the v1 [`cascade_tool_usage`](/desktop/accounts/api-reference/cascade-analytics#cascade_tool_usage)
data source, this endpoint accepts Devin service user API keys, so teams on the Cognition platform can
report tool usage without a Windsurf service key.

## Metrics

The `metric` query parameter is required and currently accepts only `calls`, the number of tool calls
the agent made. It appears as an integer `calls` field on every row. Requests without `metric`, or
naming another metric, fail with `400`.

Tool calls are counted when the agent invokes a tool in [Devin Desktop](/desktop/introducing-devin-desktop)
or the [Devin CLI](/cli) (including the CLI running as an agent inside other editors), from any model.
The `product` parameter is also required and currently accepts only `agent`.

## Tools

Group by `tool` to break calls down by tool category. Each row then includes a `tool` field with one of
the following values:

| Tool | Description |
| - | - |
| `SEARCH_WEB` | Web search, web fetch, and browser use |
| `RUN_COMMAND` | Shell commands and interacting with running processes |
| `VIEW_FILE` | Reading files and notebooks |
| `CODE_ACTION` | Editing, writing, and patching files |
| `GREP_SEARCH` | Searching file contents and code |
| `FIND` | Finding files by name |
| `LIST_DIRECTORY` | Listing directories |
| `MCP_TOOL` | Calling MCP server tools and listing MCP servers, tools, or resources |
| `SKILL` | Listing, searching, and invoking skills |
| `ASK_USER_QUESTION` | Asking the user a question |
| `MEMORY` | Reading and writing memories |
| `PROPOSE_CODE` | Proposing code changes |
| `PROXY_WEB_SERVER` | Browser preview of a local web server |
| `DEPLOY_WEB_APP` | Deploying a web app |
| `MQUERY` | Codebase search (Riptide) |
| `DEEPWIKI` | DeepWiki requests |
| `CODEMAP_GENERATION`, `CODEMAP_SUGGESTIONS` | Codemaps requests |
| `OTHER` | Devin CLI tools not in the categories above |

Not every category applies to every client: `LIST_DIRECTORY`, `MEMORY`, `PROPOSE_CODE`,
`PROXY_WEB_SERVER`, `DEPLOY_WEB_APP`, and `MQUERY` are recorded for the Devin Desktop agent, while new
Devin CLI tools that have not been assigned a category are counted under `OTHER`.

## Grouping and Granularity

Use `granularity` and `group_by` to control the shape of returned data:

* **No granularity or grouping** — returns a single aggregated row for the entire date range
* **`granularity=daily`** — each row includes a `timestamp` in `YYYY-MM-DD` format
* **`granularity=monthly`** — each row includes a `timestamp` in `YYYY-MM` format
* **`group_by=tool`** — each row includes a `tool` (see [Tools](#tools) above)
* **`group_by=user`** — each row includes a `user_id`, plus a `user_email` when one is recorded for that user
* **`group_by=model_uid`** — each row includes a `model_uid`
* **`group_by=ide`** — each row includes an `ide`
* **`group_by=ide,ide_version`** — each row includes `ide` and `ide_version` (grouping by `ide_version` requires `ide` to also be included)
* **`group_by=os`** — each row includes an `os`, such as `darwin` (macOS), `windows`, or `linux`

Dimensions can be combined, for example `group_by=user,tool` reports how often each user invoked each
tool. The `session` and `source` dimensions from [Get Output](/desktop/accounts/api-reference/get-output)
are not supported here. The same `models`, `group_id`, and `user_id` filters as
[Get Consumption](/desktop/accounts/api-reference/get-consumption) apply, plus a `tool` filter that
restricts the count to one tool category (for example `tool=SEARCH_WEB`). `tool` is only accepted by
this endpoint; passing it to another Analytics API v2 endpoint fails with `400`.

## Example

Count web searches per user for a week:

```bash theme={null}
curl "https://server.codeium.com/api/v2alpha/analytics/tools?metric=calls&product=agent&start_date=2026-10-13&end_date=2026-10-19&group_by=user&tool=SEARCH_WEB" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

Each row is one user's `SEARCH_WEB` count. Drop the `tool` filter and add `group_by=user,tool` to see every
category per user instead.

## Pagination

Results are paginated with a default page size of 1,000 rows (max 10,000). When more results are available,
the response includes a `next_page_cursor` in the `pagination` object. Pass it as the `page_cursor` query
parameter on a request that otherwise repeats the original query parameters. Cursors are bound to the endpoint that issued them; a cursor from `/consumption` or `/output`
is rejected with `400`.

Page cursors expire after 24 hours. A follow-up page request does not count as a new query against your rate limit.

## Rate Limits

This endpoint is rate-limited to **10 requests per hour** per team. If you exceed this limit, the
server returns `429 Too Many Requests` with a `Retry-After` header.

Paginating an earlier query (following a `next_page_cursor`) does **not** count against this limit —
only the initial query for each report does. The low limit reflects that this endpoint is for
periodic reporting, not real-time usage monitoring.


## OpenAPI

````yaml desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/tools
openapi: 3.1.0
info:
  title: Devin Desktop Analytics API v2
  version: 2.0.0
  description: >
    The Analytics API v2 provides credit and ACU consumption, active-user, agent
    output

    (accepted lines of code), and agent tool-call analytics for enterprise
    teams. Data is sourced from

    hourly aggregates and supports flexible filtering, grouping, and
    cursor-based pagination.
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/tools:
    get:
      summary: Get agent tool-call analytics
      description: >
        Count agent tool calls for the authenticated team. The required `metric`
        parameter accepts only

        `calls`, the number of tool calls the agent made in Devin Desktop and
        the Devin CLI, returned as an

        integer field on every row. Results can be filtered by date range,
        product, model, group, and user,

        and grouped by the same dimensions as consumption (except `session`)
        plus `tool`, the tool category

        such as `SEARCH_WEB` or `RUN_COMMAND`.


        These endpoints are designed for periodic reporting and bulk export.
        They are **not** intended for real-time usage monitoring: the rate limit
        is low (10 requests per hour per team).
      operationId: getTools
      parameters:
        - name: metric
          in: query
          required: true
          schema:
            type: string
          description: >
            Metric to return; appears as a field on every row. Supported
            metrics:

            - `calls` — number of tool calls the agent made
          example: calls
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Start of the date range (inclusive) in `YYYY-MM-DD` format.
          example: '2026-10-01'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: >-
            End of the date range (inclusive) in `YYYY-MM-DD` format. The range
            must not exceed 90 days.
          example: '2026-10-31'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Product to query tool calls for.
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: >
            Time granularity for grouping results. When specified, each row
            includes a `timestamp` field.

            If omitted, results are aggregated across the entire date range.
        - name: group_by
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-separated list of dimensions to group results by. Supported
            dimensions:

            - `tool` — includes `tool` in each row (the tool category, such as
            `SEARCH_WEB` or `RUN_COMMAND`)

            - `user` — includes `user_id` in each row, plus `user_email` when
            one is recorded for the user

            - `model_uid` — includes `model_uid` in each row

            - `ide` — includes `ide` in each row

            - `ide_version` — includes `ide_version` in each row; requires `ide`
            to also be included

            - `os` — includes `os` in each row
          example: user,tool
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of model UIDs to filter results to.
          example: swe-2-high,claude-4-sonnet
        - name: tool
          in: query
          required: false
          schema:
            type: string
          description: >
            Restrict the count to one tool category, such as `SEARCH_WEB` or
            `RUN_COMMAND` (exact match).

            Only accepted by this endpoint.
          example: SEARCH_WEB
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filter results to users in a specific group. The service key must
            have access to this group. Not supported with Devin service user API
            keys.
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: Filter results to a specific user (auth UID).
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
          description: Maximum number of rows to return per page.
        - name: page_cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque cursor from a previous response's
            `pagination.next_page_cursor` to fetch the next page. Pass the same
            `metric` as the request that issued it; cursors issued by other
            endpoints are rejected.
      responses:
        '200':
          description: Tool-call data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolsResponse'
              examples:
                by_user_tool:
                  summary: Web searches and commands per user
                  value:
                    data:
                      - user_id: user_abc123
                        user_email: alice@example.com
                        tool: RUN_COMMAND
                        calls: 1842
                      - user_id: user_abc123
                        user_email: alice@example.com
                        tool: SEARCH_WEB
                        calls: 57
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-10-20T02:00:00Z'
                      query_time_ms: 1104
                      team_id: team_abc123
                daily_total:
                  summary: granularity=daily with no grouping
                  value:
                    data:
                      - timestamp: '2026-10-13'
                        calls: 48210
                      - timestamp: '2026-10-14'
                        calls: 51377
                    pagination:
                      next_page_cursor: null
                    metadata:
                      data_freshness: '2026-10-20T02:00:00Z'
                      query_time_ms: 870
                      team_id: team_abc123
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_metric:
                  value:
                    error: metric is required
                bad_metric:
                  value:
                    error: 'unsupported metric: loc_inserted (supported: calls)'
                missing_product:
                  value:
                    error: product is required
                bad_group_by:
                  value:
                    error: 'unsupported group_by dimension for tools: session'
        '401':
          description: Authentication failed or insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_auth:
                  value:
                    error: missing Authorization header
                invalid_key:
                  value:
                    error: invalid service key
                insufficient_permissions:
                  value:
                    error: insufficient permissions
        '403':
          description: >-
            The supplied page cursor does not belong to the authenticated team
            or requested group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                cursor_team_mismatch:
                  value:
                    error: page cursor does not belong to this team
        '405':
          description: HTTP method not allowed (only `GET` is supported).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Rate limit exceeded (10 requests per hour per team). Paginating an
            earlier query does not count against this limit.
          headers:
            Retry-After:
              schema:
                type: string
              description: Suggested wait time before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error: rate limit exceeded
        '503':
          description: >-
            Analytics service is not available (e.g., in self-hosted
            deployments).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ToolsResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ToolsRow'
          description: Array of tool-call data rows.
        pagination:
          type: object
          properties:
            next_page_cursor:
              type:
                - string
                - 'null'
              description: >
                Opaque cursor for fetching the next page of results. Pass this
                value as the `page_cursor`

                query parameter in a follow-up request. `null` when there are no
                more pages.

                Page cursors expire after 24 hours.
        metadata:
          type: object
          properties:
            data_freshness:
              type: string
              format: date-time
              description: >-
                Timestamp indicating when the underlying data was last refreshed
                (truncated to the hour).
            query_time_ms:
              type: integer
              format: int64
              description: Server-side query execution time in milliseconds.
            team_id:
              type: string
              description: The team ID resolved from the authenticated service key.
            group_id:
              type: string
              description: >-
                The group ID the results were scoped to. Only present when
                `group_id` was supplied.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    ToolsRow:
      type: object
      required:
        - calls
      properties:
        timestamp:
          type: string
          description: >
            Time bucket for the row. Format depends on `granularity`:
            `YYYY-MM-DD` for daily, `YYYY-MM` for monthly.

            Only present when `granularity` is specified.
          examples:
            - '2026-10-15'
            - 2026-10
        user_id:
          type: string
          description: >-
            User identifier (auth UID). Only present when `group_by` includes
            `user`.
        user_email:
          type: string
          description: >-
            User's email address. Only present when `group_by` includes `user`
            and an email is recorded for the user.
          examples:
            - alice@example.com
        model_uid:
          type: string
          description: Model identifier. Only present when `group_by` includes `model_uid`.
          examples:
            - swe-2-high
        ide:
          type: string
          description: IDE name. Only present when `group_by` includes `ide`.
          examples:
            - windsurf
            - devin-cli
        ide_version:
          type: string
          description: >-
            IDE version. Only present when `group_by` includes `ide_version`
            (which additionally requires `ide`).
          examples:
            - 3000.10.48
        os:
          type: string
          description: >-
            Operating system the request came from. Only present when `group_by`
            includes `os`.
          examples:
            - darwin
            - windows
            - linux
        tool:
          type: string
          description: >
            Tool category the calls were made with, such as `SEARCH_WEB`,
            `RUN_COMMAND`, `VIEW_FILE`,

            `CODE_ACTION`, `GREP_SEARCH`, `FIND`, `MCP_TOOL`, `SKILL`, or
            `ASK_USER_QUESTION`. Devin CLI tools

            without a category are reported as `OTHER`. Only present when
            `group_by` includes `tool`.
          examples:
            - SEARCH_WEB
            - RUN_COMMAND
        calls:
          type: integer
          format: int64
          description: Number of agent tool calls in this row.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        A service key with **Analytics Read** permission, passed as a Bearer
        token in the `Authorization` header.


        Create a service key in your [team
        settings](https://windsurf.com/team/settings) under the "Service Keys"
        section.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.