> ## Documentation Index > Fetch the complete documentation index at: https://docs.devin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Obter chamadas de ferramentas do agente Devin > Conte as chamadas de ferramentas do agente, como busca na web ou execução de comandos, feitas pela sua equipe no Devin Desktop e no Devin CLI, agrupadas por ferramenta, usuário, modelo, IDE ou sistema operacional. Este é um **endpoint v2** que usa autenticação com Token Bearer e parâmetros de consulta, ao contrário da API de Análise v1, que usa chaves de serviço no corpo da requisição. Veja [Autenticação](#authentication) abaixo. Este endpoint **não** foi projetado para monitoramento de uso em tempo real. O limite de taxa de requisições é baixo (10 requisições por hora por equipe). Use-o para relatórios periódicos e exportação em massa.

Autenticação

Este endpoint usa autenticação via **Token Bearer**. Inclua seu token no cabeçalho `Authorization`: ``` Authorization: Bearer ``` Use uma chave de API de usuário de serviço do Devin com a permissão **Usar API de análises local** ou uma chave de serviço do Windsurf com a permissão **Analytics Read**. Consulte [Autenticação](/pt-BR/desktop/accounts/api-reference/analytics-v2-introduction#authentication) para saber como criar cada uma. Diferentemente da fonte de dados [`cascade_tool_usage`](/pt-BR/desktop/accounts/api-reference/cascade-analytics#cascade_tool_usage) da v1, este endpoint aceita chaves de API de usuário de serviço do Devin. Assim, equipes na plataforma da Cognition podem gerar relatórios de uso de ferramentas sem precisar de uma chave de serviço do Windsurf.

Métricas

O parâmetro de consulta `metric` é obrigatório e, no momento, aceita apenas `calls`, o número de chamadas de ferramenta feitas pelo agente. Ele aparece como um campo inteiro `calls` em todas as linhas. Requisições sem `metric`, ou que especifiquem outra métrica, falham com `400`. As chamadas de ferramentas são contabilizadas quando o agente invoca uma ferramenta no [Devin Desktop](/pt-BR/desktop/introducing-devin-desktop) ou na [Devin CLI](/pt-BR/cli) (incluindo a CLI executada como agente dentro de outros editores), com qualquer modelo. O parâmetro `product` também é obrigatório e, no momento, aceita apenas `agent`.

Ferramentas

Agrupe por `tool` para dividir as chamadas por categoria de ferramenta. Assim, cada linha inclui um campo `tool` com um dos seguintes valores: | Ferramenta | Descrição | | - | - | | `SEARCH_WEB` | Busca na web, requisições à web (fetch) e uso do navegador | | `RUN_COMMAND` | Comandos de shell e interação com processos em execução | | `VIEW_FILE` | Leitura de arquivos e notebooks | | `CODE_ACTION` | Edição, escrita e aplicação de patches em arquivos | | `GREP_SEARCH` | Pesquisa no conteúdo de arquivos e no código | | `FIND` | Localização de arquivos pelo nome | | `LIST_DIRECTORY` | Listagem de diretórios | | `MCP_TOOL` | Chamada de ferramentas de servidores MCP e listagem de servidores MCP, ferramentas ou recursos | | `SKILL` | Listagem, pesquisa e invocação de habilidades | | `ASK_USER_QUESTION` | Envio de perguntas ao usuário | | `MEMORY` | Leitura e escrita de memórias | | `PROPOSE_CODE` | Proposta de alterações no código | | `PROXY_WEB_SERVER` | Prévia no navegador de um servidor web local | | `DEPLOY_WEB_APP` | Implantação de um web app | | `MQUERY` | Pesquisa na base de código (Riptide) | | `DEEPWIKI` | Requisições ao DeepWiki | | `CODEMAP_GENERATION`, `CODEMAP_SUGGESTIONS` | Requisições ao Codemaps | | `OTHER` | Ferramentas do Devin CLI que não se enquadram nas categorias acima | Nem todas as categorias se aplicam a todos os clientes: `LIST_DIRECTORY`, `MEMORY`, `PROPOSE_CODE`, `PROXY_WEB_SERVER`, `DEPLOY_WEB_APP` e `MQUERY` são registradas para o agente do Devin Desktop, enquanto as novas ferramentas do Devin CLI que ainda não foram atribuídas a uma categoria são contabilizadas em `OTHER`.

Agrupamento e granularidade

Use `granularity` e `group_by` para controlar o formato dos dados retornados: * **Sem granularidade nem agrupamento** — retorna uma única linha agregada para todo o intervalo de datas * **`granularity=daily`** — cada linha inclui um `timestamp` no formato `YYYY-MM-DD` * **`granularity=monthly`** — cada linha inclui um `timestamp` no formato `YYYY-MM` * **`group_by=tool`** — cada linha inclui um `tool` (consulte [Ferramentas](#tools) acima) * **`group_by=user`** — cada linha inclui um `user_id`, além de um `user_email` quando houver um registrado para esse usuário * **`group_by=model_uid`** — cada linha inclui um `model_uid` * **`group_by=ide`** — cada linha inclui um `ide` * **`group_by=ide,ide_version`** — cada linha inclui `ide` e `ide_version` (agrupar por `ide_version` exige que `ide` também seja incluído) * **`group_by=os`** — cada linha inclui um `os`, como `darwin` (macOS), `windows` ou `linux` É possível combinar dimensões; por exemplo, `group_by=user,tool` mostra com que frequência cada usuário invocou cada ferramenta. As dimensões `session` e `source` de [Get Output](/pt-BR/desktop/accounts/api-reference/get-output) não são compatíveis aqui. Valem os mesmos filtros `models`, `group_id` e `user_id` de [Get Consumption](/pt-BR/desktop/accounts/api-reference/get-consumption), além de um filtro `tool` que restringe a contagem a uma única categoria de ferramenta (por exemplo, `tool=SEARCH_WEB`). `tool` só é aceito por este endpoint; enviá-lo a outro endpoint da Analytics API v2 resulta em erro `400`.

Exemplo

Contar as buscas na web por usuário em uma semana: ```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" ``` Cada linha corresponde à contagem de `SEARCH_WEB` de um usuário. Para ver todas as categorias de cada usuário, remova o filtro `tool` e adicione `group_by=user,tool`.

Paginação

Os resultados são paginados com um tamanho de página padrão de 1.000 linhas (máximo de 10.000). Quando houver mais resultados disponíveis, a resposta inclui um `next_page_cursor` no objeto `pagination`. Passe-o como o parâmetro de consulta `page_cursor` em uma requisição que repita os demais parâmetros de consulta originais. Os cursores ficam vinculados ao endpoint que os emitiu; um cursor de `/consumption` ou `/output` é rejeitado com `400`. Os cursores de página expiram após 24 horas. Requisições das páginas seguintes não contam como novas consultas para o seu limite de taxa de requisições.

Limites de requisições

Este endpoint tem um limite de taxa de requisições de **10 requisições por hora** por equipe. Se você exceder esse limite, o servidor retornará `429 Too Many Requests` com um cabeçalho `Retry-After`. Paginar uma consulta anterior (usando um `next_page_cursor`) **não** conta para esse limite — apenas a consulta inicial de cada relatório é contabilizada. O limite baixo se deve ao fato de que este endpoint é destinado a relatórios periódicos, e não ao monitoramento de uso em tempo real. ## OpenAPI ````yaml pt-BR/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: > A Analytics API v2 fornece análises de consumo de créditos e ACU, de usuários ativos, do output tipado do agente (linhas de código aceitas) e de chamadas de ferramentas do agente para equipes Enterprise. Os dados são obtidos de agregações por hora e oferecem suporte a filtragem flexível, agrupamento e paginação baseada em cursor. servers: - url: https://server.codeium.com security: - bearerAuth: [] paths: /api/v2alpha/analytics/tools: get: summary: Obter análises de chamadas de ferramentas do agente description: > Contar chamadas de ferramentas do agente para a equipe autenticada. O parâmetro obrigatório `metric` aceita apenas `calls`, o número de chamadas de ferramentas feitas pelo agente no Devin Desktop e no Devin CLI, retornado como um campo inteiro em cada linha. Os resultados podem ser filtrados por intervalo de datas, produto, modelo, grupo e usuário, e agrupados pelas mesmas dimensões do consumo (exceto `session`), além de `tool`, que indica a categoria da ferramenta, como `SEARCH_WEB` ou `RUN_COMMAND`. Esses endpoints foram projetados para relatórios periódicos e exportação em massa. Eles **não** se destinam ao monitoramento de uso em tempo real: o limite de taxa de requisições é baixo (10 requisições por hora por equipe). operationId: getTools parameters: - name: metric in: query required: true schema: type: string description: > Métrica a ser retornada; aparece como um campo em cada linha. Métricas disponíveis: - `calls` — número de chamadas de ferramentas feitas pelo agente example: calls - name: start_date in: query required: true schema: type: string format: date description: Início do intervalo de datas (inclusivo) no formato `YYYY-MM-DD`. example: '2026-10-01T00:00:00.000Z' - name: end_date in: query required: true schema: type: string format: date description: >- Fim do intervalo de datas (inclusivo) no formato `YYYY-MM-DD`. O intervalo não deve exceder 90 dias. example: '2026-10-31T00:00:00.000Z' - name: product in: query required: true schema: type: string enum: - agent description: Produto cujas chamadas de ferramentas serão consultadas. example: agent - name: granularity in: query required: false schema: type: string enum: - daily - monthly description: > Granularidade temporal para agrupar resultados. Quando especificada, cada linha inclui um campo `timestamp`. Se omitida, os resultados são agregados para todo o intervalo de datas. - name: group_by in: query required: false schema: type: string description: > Lista de dimensões separadas por vírgulas para agrupar os resultados. Dimensões compatíveis: - `tool` — inclui `tool` em cada linha (a categoria de ferramenta, como `SEARCH_WEB` ou `RUN_COMMAND`) - `user` — inclui `user_id` em cada linha, além de `user_email` quando houver um e-mail registrado para o usuário - `model_uid` — inclui `model_uid` em cada linha - `ide` — inclui `ide` em cada linha - `ide_version` — inclui `ide_version` em cada linha; exige que `ide` também seja incluído - `os` — inclui `os` em cada linha example: user,tool - name: models in: query required: false schema: type: string description: >- Lista de UIDs de modelos, separados por vírgulas, para filtrar os resultados. example: swe-2-high,claude-4-sonnet - name: tool in: query required: false schema: type: string description: > Restringe a contagem a uma única categoria de ferramenta, como `SEARCH_WEB` ou `RUN_COMMAND` (correspondência exata). Aceito apenas por este endpoint. example: SEARCH_WEB - name: group_id in: query required: false schema: type: string description: >- Filtra os resultados para incluir apenas usuários de um grupo específico. A chave de serviço deve ter acesso a esse grupo. Não pode ser usado com chaves de API do usuário de serviço do Devin. - name: user_id in: query required: false schema: type: string description: >- Filtra os resultados para incluir apenas um usuário específico (UID de autenticação). - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 10000 default: 1000 description: Número máximo de linhas a retornar por página. - name: page_cursor in: query required: false schema: type: string description: >- Cursor opaco obtido de `pagination.next_page_cursor` em uma resposta anterior, usado para buscar a próxima página. Envie o mesmo `metric` usado na requisição que gerou o cursor; cursores gerados por outros endpoints são rejeitados. responses: '200': description: Dados de chamadas de ferramentas retornados com sucesso. content: application/json: schema: $ref: '#/components/schemas/ToolsResponse' examples: by_user_tool: summary: Buscas na web e comandos por usuário 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:00.000Z' query_time_ms: 1104 team_id: team_abc123 daily_total: summary: granularity=daily sem agrupamento value: data: - timestamp: '2026-10-13T00:00:00.000Z' calls: 48210 - timestamp: '2026-10-14T00:00:00.000Z' calls: 51377 pagination: next_page_cursor: null metadata: data_freshness: '2026-10-20T02:00:00.000Z' query_time_ms: 870 team_id: team_abc123 '400': description: Parâmetros da requisição inválidos. 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: Falha na autenticação ou permissões insuficientes. 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: >- O cursor de página fornecido não pertence à equipe autenticada ou ao grupo solicitado. content: application/json: schema: $ref: '#/components/schemas/Error' examples: cursor_team_mismatch: value: error: page cursor does not belong to this team '405': description: Método HTTP não permitido (apenas `GET` é aceito). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Limite de requisições excedido (10 requisições por hora por equipe). A paginação de uma consulta anterior não é contabilizada nesse limite. headers: Retry-After: schema: type: string description: Tempo de espera sugerido antes de tentar novamente. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: rate limit exceeded '503': description: >- Serviço de análise indisponível (p. ex., em implantações auto-hospedadas). 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 de linhas com dados de chamadas de ferramentas. pagination: type: object properties: next_page_cursor: type: - string - 'null' description: > Cursor opaco para buscar a próxima página de resultados. Passe esse valor no parâmetro de consulta `page_cursor` em uma requisição subsequente. `null` quando não há mais páginas. Os cursores de página expiram após 24 horas. metadata: type: object properties: data_freshness: type: string format: date-time description: >- Carimbo de data/hora que indica a última atualização dos dados subjacentes (truncado para a hora). query_time_ms: type: integer format: int64 description: Tempo de execução da consulta server-side em milissegundos. team_id: type: string description: >- O ID da equipe resolvido a partir da chave de serviço autenticada. group_id: type: string description: >- O ID do grupo usado para definir o escopo dos resultados. Presente somente quando `group_id` foi fornecido. Error: type: object required: - error properties: error: type: string description: Mensagem de erro legível por humanos. ToolsRow: type: object required: - calls properties: timestamp: type: string description: > Intervalo de tempo da linha. O formato depende de `granularity`: `YYYY-MM-DD` para granularidade diária e `YYYY-MM` para mensal. Presente somente quando `granularity` é especificado. examples: - '2026-10-15T00:00:00.000Z' - 2026-10 user_id: type: string description: >- Identificador do usuário (UID de autenticação). Presente somente quando `group_by` inclui `user`. user_email: type: string description: >- Endereço de e-mail do usuário. Presente somente quando `group_by` inclui `user` e há um e-mail registrado para o usuário. examples: - alice@example.com model_uid: type: string description: >- Identificador do modelo. Presente somente quando `group_by` inclui `model_uid`. examples: - swe-2-high ide: type: string description: Nome da IDE. Presente somente quando `group_by` inclui `ide`. examples: - windsurf - devin-cli ide_version: type: string description: >- Versão da IDE. Presente somente quando `group_by` inclui `ide_version` (que também exige `ide`). examples: - 3000.10.48 os: type: string description: >- Sistema operacional de origem da requisição. Presente somente quando `group_by` inclui `os`. examples: - darwin - windows - linux tool: type: string description: > Categoria da ferramenta usada nas chamadas, como `SEARCH_WEB`, `RUN_COMMAND`, `VIEW_FILE`, `CODE_ACTION`, `GREP_SEARCH`, `FIND`, `MCP_TOOL`, `SKILL` ou `ASK_USER_QUESTION`. Ferramentas do Devin CLI sem categoria são indicadas como `OTHER`. Presente somente quando `group_by` inclui `tool`. examples: - SEARCH_WEB - RUN_COMMAND calls: type: integer format: int64 description: Número de chamadas de ferramentas do agente nesta linha. securitySchemes: bearerAuth: type: http scheme: bearer description: > Uma service key com permissão **Analytics Read**, enviada como token Bearer no header `Authorization`. Crie uma service key em [Configurações da equipe](https://windsurf.com/team/settings), na seção "Service Keys". ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.