Skip to main content
GET
Get agent tool-call analytics
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 below.
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.

Authentication

This endpoint uses Bearer token authentication. Include your token in the Authorization header:
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 for how to create each one. Unlike the v1 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 or the Devin 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: 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 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 are not supported here. The same models, group_id, and user_id filters as 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:
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.

Authorizations

Authorization
string
header
required

A service key with Analytics Read permission, passed as a Bearer token in the Authorization header.

Create a service key in your team settings under the "Service Keys" section.

Query Parameters

metric
string
required

Metric to return; appears as a field on every row. Supported metrics:

  • calls — number of tool calls the agent made
start_date
string<date>
required

Start of the date range (inclusive) in YYYY-MM-DD format.

end_date
string<date>
required

End of the date range (inclusive) in YYYY-MM-DD format. The range must not exceed 90 days.

product
enum<string>
required

Product to query tool calls for.

Available options:
agent
granularity
enum<string>

Time granularity for grouping results. When specified, each row includes a timestamp field. If omitted, results are aggregated across the entire date range.

Available options:
daily,
monthly
group_by
string

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
models
string

Comma-separated list of model UIDs to filter results to.

tool
string

Restrict the count to one tool category, such as SEARCH_WEB or RUN_COMMAND (exact match). Only accepted by this endpoint.

group_id
string

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.

user_id
string

Filter results to a specific user (auth UID).

page_size
integer
default:1000

Maximum number of rows to return per page.

Required range: 1 <= x <= 10000
page_cursor
string

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.

Response

Tool-call data returned successfully.

data
object[]
required

Array of tool-call data rows.

pagination
object
required
metadata
object
required