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

# Consultar consumo

> Consulte análises de consumo de créditos ou ACU com filtragem, agrupamento e paginação flexíveis.

<Note>
  Este é um **endpoint v2** que usa autenticação com token Bearer e parâmetros de consulta, ao contrário da Analytics API v1, que usa chaves de serviço no corpo da requisição. Veja [Autenticação](#authentication) abaixo.
</Note>

<Warning>
  Este endpoint **não** se destina ao monitoramento de uso em tempo real. Os dados são agregados por hora, e o
  limite de taxa é baixo (10 requisições por hora por equipe). Use-o para relatórios periódicos e exportação em massa.
</Warning>

<div id="authentication">
  ## Autenticação
</div>

Este endpoint usa autenticação com **token Bearer**. Inclua sua chave de serviço no cabeçalho `Authorization`:

```
Authorization: Bearer <your_service_key>
```

A chave de serviço deve ter a permissão **Leitura de análises**. Crie uma nas [Configurações da equipe](https://windsurf.com/team/settings), em "Service Keys".

<div id="billing-strategy">
  ## Estratégia de faturamento
</div>

A estrutura da resposta depende da estratégia de faturamento da sua equipe:

| Estratégia | Campos preenchidos               | Descrição                        |
| ---------- | -------------------------------- | -------------------------------- |
| `CREDITS`  | `prompt_credits`, `flex_credits` | equipes Standard Enterprise SaaS |
| `ACU`      | `billed_acus`                    | equipes faturadas por ACUs       |

O campo `message_count` (dentro de `consumption`) é sempre preenchido, independentemente da estratégia de faturamento.

<div id="grouping-and-granularity">
  ## Agrupamento e granularidade
</div>

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=user`** — cada linha inclui `user_id` e `user_email`
* **`group_by=user,model_uid`** — cada linha inclui `user_id`, `user_email` e `model_uid`
* **`group_by=ide`** — cada linha inclui `ide`

<div id="pagination">
  ## Paginação
</div>

Os resultados são paginados com um tamanho de página padrão de 1.000 linhas (máx. 10.000). Quando houver mais resultados disponíveis,
a resposta incluirá um `next_page_cursor` no objeto `pagination`. Passe-o como parâmetro de query `page_cursor`
para obter a próxima página.

Os cursores de página expiram após 24 horas. Uma requisição subsequente de página não conta como uma nova consulta para o seu limite de taxa.

<div id="caching">
  ## Cache
</div>

As respostas incluem um cabeçalho `ETag`. Para evitar transferência desnecessária de dados, inclua o cabeçalho `If-None-Match`
com o valor anterior de `ETag` — o servidor retornará `304 Not Modified` se os dados não tiverem sido alterados.

<div id="rate-limits">
  ## Limites de taxa
</div>

Este endpoint tem um limite 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 (seguindo um `next_page_cursor`) **não** entra nesse limite —
apenas a consulta inicial de cada relatório entra. Esse limite baixo reflete o fato de que este endpoint é para
relatórios periódicos, não para monitoramento de uso em tempo real.


## OpenAPI

````yaml pt-BR/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
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 para
    equipes Enterprise.

    Os dados são obtidos de eventos de faturamento agregados por hora e oferecem
    suporte a filtragem, agrupamento

    e paginação baseada em cursor.
servers:
  - url: https://server.codeium.com
security:
  - bearerAuth: []
paths:
  /api/v2alpha/analytics/consumption:
    get:
      summary: Obter análises de consumo
      description: >
        Consulte os dados de consumo de créditos ou ACU da equipe autenticada.
        Os resultados são obtidos de

        eventos de faturamento agregados por hora e podem ser filtrados por
        intervalo de datas, produto, modelo e grupo.


        O formato da resposta depende da estratégia de faturamento da equipe:

        - Equipes **baseadas em créditos** recebem `prompt_credits` e
        `flex_credits` em cada linha.

        - Equipes **baseadas em ACU** recebem `billed_acus` em cada linha.


        As respostas são armazenadas em cache por 1 hora. Use `If-None-Match`
        com um `ETag` retornado anteriormente para

        receber um `304 Not Modified` quando os dados não tiverem sido
        alterados.


        Esses endpoints foram projetados para relatórios periódicos e exportação
        em massa. **Não** se destinam ao monitoramento de uso em tempo real: os
        dados são agregados por hora e o limite de taxa é baixo (10 requisições
        por hora por equipe).
      operationId: getConsumption
      parameters:
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Início do intervalo de datas (inclusive), no formato `YYYY-MM-DD`.
          example: '2026-01-01T00:00:00.000Z'
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: >-
            Fim do intervalo de datas (inclusive), no formato `YYYY-MM-DD`. O
            intervalo não deve exceder 90 dias.
          example: '2026-01-31T00:00:00.000Z'
        - name: product
          in: query
          required: true
          schema:
            type: string
            enum:
              - agent
          description: Produto para consultar o consumo.
          example: agent
        - name: granularity
          in: query
          required: false
          schema:
            type: string
            enum:
              - daily
              - monthly
          description: >
            Granularidade de tempo para agrupar os resultados. Quando
            especificada, cada linha inclui um campo `timestamp`.

            Se omitida, os resultados são agregados em 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:

            - `user` — inclui `user_id` e `user_email` em cada linha

            - `model_uid` — inclui `model_uid` em cada linha

            - `ide` — inclui `ide` em cada linha
          example: user,model_uid
        - name: models
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lista de UIDs de modelo, separados por vírgulas, para filtrar os
            resultados.
          example: claude-4-sonnet,gpt-4.1
        - name: group_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtre os resultados para usuários de um grupo específico. A service
            key deve ter acesso a esse grupo.
        - name: user_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Filtre os resultados para 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 de `pagination.next_page_cursor` de uma resposta
            anterior para buscar a próxima página.
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
          description: >-
            Valor de ETag de uma resposta anterior. Se os dados não tiverem sido
            alterados, o servidor retornará `304 Not Modified`.
      responses:
        '200':
          description: Dados de consumo retornados com sucesso.
          headers:
            ETag:
              schema:
                type: string
              description: >-
                Tag de entidade para validação de cache. Passe isto como
                `If-None-Match` em requisições subsequentes.
            Cache-Control:
              schema:
                type: string
              description: Diretiva de cache (por exemplo, `private, max-age=3600`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionResponse'
              examples:
                credits:
                  summary: Equipe baseada em créditos com granularidade diária
                  value:
                    data:
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_abc123
                        user_email: alice@example.com
                        consumption:
                          prompt_credits: 1250
                          flex_credits: 340
                          message_count: 87
                      - timestamp: '2026-01-15T00:00:00.000Z'
                        user_id: user_def456
                        user_email: bob@example.com
                        consumption:
                          prompt_credits: 980
                          flex_credits: 150
                          message_count: 52
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: CREDITS
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 1423
                      team_id: team_abc123
                acu:
                  summary: Equipe baseada em ACU
                  value:
                    data:
                      - consumption:
                          billed_acus: 42.75
                          message_count: 310
                    pagination:
                      next_page_cursor: null
                    metadata:
                      billing_strategy: ACU
                      data_freshness: '2026-01-16T03:00:00.000Z'
                      query_time_ms: 892
                      team_id: team_def456
        '304':
          description: >-
            Os dados não foram alterados desde o ETag fornecido em
            `If-None-Match`.
        '400':
          description: Parâmetros de requisição inválidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_param:
                  value:
                    error: start_date is required
                date_range:
                  value:
                    error: date range must not exceed 90 days
                bad_product:
                  value:
                    error: 'unsupported product: foo (supported: agent)'
        '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 nem
            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 (somente `GET` é compatível).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Limite de taxa excedido (10 requisições por hora por equipe).
            Paginar uma consulta anterior não conta para esse 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: >-
            O serviço de análises não está disponível (por exemplo, em
            implantações auto-hospedadas).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    ConsumptionResponse:
      type: object
      required:
        - data
        - pagination
        - metadata
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ConsumptionRow'
          description: Array de linhas de dados de consumo.
        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 como parâmetro de consulta `page_cursor`

                em uma requisição seguinte. `null` quando não houver mais
                páginas.

                Os cursores de página expiram após 24 horas.
        metadata:
          type: object
          properties:
            billing_strategy:
              type: string
              enum:
                - CREDITS
                - ACU
              description: >
                A estratégia de faturamento da equipe autenticada. Determina
                quais campos em `consumption` são preenchidos:

                - `CREDITS` — `prompt_credits` e `flex_credits`

                - `ACU` — `billed_acus`
            data_freshness:
              type: string
              format: date-time
              description: >-
                Timestamp que indica quando os dados subjacentes foram
                atualizados pela última vez (truncado para a hora).
            query_time_ms:
              type: integer
              format: int64
              description: Tempo de execução da consulta no servidor, em milissegundos.
            team_id:
              type: string
              description: O ID da equipe resolvido a partir da service key autenticada.
            group_id:
              type: string
              description: >-
                O ID do grupo ao qual os resultados se aplicam. Presente apenas
                quando `group_id` é fornecido.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Mensagem de erro legível por humanos.
    ConsumptionRow:
      type: object
      required:
        - consumption
      properties:
        timestamp:
          type: string
          description: >
            Intervalo de tempo da linha. O formato depende de `granularity`:
            `YYYY-MM-DD` para diário, `YYYY-MM` para mensal.

            Presente apenas quando `granularity` é especificado.
          examples:
            - '2026-05-01T00:00:00.000Z'
            - 2026-05
        user_id:
          type: string
          description: >-
            Identificador do usuário (UID de autenticação). Presente apenas
            quando `group_by` inclui `user`.
        user_email:
          type: string
          description: >-
            Endereço de e-mail do usuário. Presente apenas quando `group_by`
            inclui `user`.
          examples:
            - alice@example.com
        model_uid:
          type: string
          description: >-
            Identificador do modelo. Presente apenas quando `group_by` inclui
            `model_uid`.
          examples:
            - claude-4-sonnet
        ide:
          type: string
          description: Nome da IDE. Presente apenas quando `group_by` inclui `ide`.
          examples:
            - windsurf
            - jetbrains
        consumption:
          $ref: '#/components/schemas/Consumption'
    Consumption:
      type: object
      description: >-
        Métricas de uso da linha. Os campos são preenchidos com base na
        estratégia de faturamento da equipe.
      properties:
        prompt_credits:
          type: integer
          format: int64
          description: >-
            Créditos de prompt consumidos (somente para faturamento baseado em
            créditos).
        flex_credits:
          type: integer
          format: int64
          description: >-
            Créditos Flex consumidos (somente para faturamento baseado em
            créditos).
        billed_acus:
          type: number
          format: double
          description: ACUs faturados consumidos (somente para faturamento baseado em ACU).
        message_count:
          type: integer
          format: int64
          description: >-
            Número de mensagens (eventos de faturamento) nesta linha. Sempre
            preenchido, independentemente da estratégia de faturamento.
  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".

````