> ## 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.
# Obtener consumo
> Consulta analíticas de consumo de créditos o ACU con filtrado, agrupación y paginación flexibles.
Este es un **endpoint v2** que usa autenticación con token Bearer y parámetros de consulta, a diferencia de la Analytics API v1, que usa claves de servicio en el cuerpo de la solicitud. Consulta [Autenticación](#authentication) más abajo.
Este endpoint **no** está pensado para el seguimiento del uso en tiempo real. Los datos se agregan por hora y el
límite de tasa es bajo (10 solicitudes por hora por equipo). Úsalo para informes periódicos y exportaciones masivas.
## Autenticación
Este endpoint utiliza autenticación mediante **token Bearer**. Incluye tu clave de servicio en el encabezado `Authorization`:
```
Authorization: Bearer
```
La clave de servicio debe tener el permiso **Analytics Read**. Crea una en tu [Team Settings](https://windsurf.com/team/settings), en "Service Keys".
## Estrategia de facturación
La estructura de la respuesta depende de la estrategia de facturación de tu equipo:
| Estrategia | Campos completados | Descripción |
| ---------- | -------------------------------- | ----------------------------------------------------- |
| `CREDITS` | `prompt_credits`, `flex_credits` | Equipos Standard de Enterprise SaaS |
| `ACU` | `billed_acus` | Equipos facturados por unidades de cómputo del agente |
El campo `message_count` (dentro de `consumption`) siempre está presente, independientemente de la estrategia de facturación.
## Agrupación y granularidad
Usa `granularity` y `group_by` para controlar la estructura de los datos devueltos:
* **Sin granularidad ni agrupación** — devuelve una única fila agregada para todo el intervalo de fechas
* **`granularity=daily`** — cada fila incluye una marca de tiempo (`timestamp`) en formato `YYYY-MM-DD`
* **`granularity=monthly`** — cada fila incluye una marca de tiempo (`timestamp`) en formato `YYYY-MM`
* **`group_by=user`** — cada fila incluye un `user_id` y `user_email`
* **`group_by=user,model_uid`** — cada fila incluye `user_id`, `user_email` y `model_uid`
* **`group_by=ide`** — cada fila incluye un `ide`
Los resultados se paginan con un tamaño de página predeterminado de 1.000 filas (máx. 10.000). Cuando hay más resultados,
la respuesta incluye un `next_page_cursor` en el objeto `pagination`. Pásalo como el parámetro de consulta `page_cursor`
para obtener la página siguiente.
Los cursores de página caducan al cabo de 24 horas. Una solicitud posterior para obtener otra página no cuenta como una nueva consulta para tu límite de tasa.
## Almacenamiento en caché
Las respuestas incluyen un encabezado `ETag`. Para evitar transferencias de datos redundantes, incluye el encabezado `If-None-Match`
con el valor anterior de `ETag`; el servidor devolverá `304 Not Modified` si los datos no han cambiado.
## Límites de tasa
Este endpoint está sujeto a un límite de **10 solicitudes por hora** por equipo. Si supera este límite, el
servidor devuelve `429 Too Many Requests` con un encabezado `Retry-After`.
Paginar una consulta anterior (siguiendo un `next_page_cursor`) **no** cuenta para este límite:
solo cuenta la consulta inicial de cada informe. El límite bajo refleja que este endpoint está pensado para
informes periódicos, no para la supervisión del uso en tiempo real.
## OpenAPI
````yaml es/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: >
La Analytics API v2 proporciona analíticas de consumo de créditos y ACU para
equipos Enterprise.
Los datos proceden de eventos de facturación agregados por hora y admite
filtros flexibles, agrupación
y paginación basada en cursor.
servers:
- url: https://server.codeium.com
security:
- bearerAuth: []
paths:
/api/v2alpha/analytics/consumption:
get:
summary: Obtener analíticas de consumo
description: >
Consulta los datos de consumo de créditos o ACU del equipo autenticado.
Los resultados provienen de eventos de facturación agregados por hora y
se pueden filtrar por rango de fechas, producto, modelo y grupo.
La estructura de la respuesta depende de la estrategia de facturación
del equipo:
- Los equipos **basados en créditos** reciben `prompt_credits` y
`flex_credits` en cada fila.
- Los equipos **basados en ACU** reciben `billed_acus` en cada fila.
Las respuestas se almacenan en caché durante 1 hora. Usa `If-None-Match`
con un `ETag` devuelto previamente para recibir un `304 Not Modified`
cuando los datos no hayan cambiado.
Estos endpoints están diseñados para informes periódicos y exportaciones
masivas. **No** están pensados para supervisar el uso en tiempo real:
los datos se agregan por hora y el límite de tasa es bajo (10
solicitudes por hora por equipo).
operationId: getConsumption
parameters:
- name: start_date
in: query
required: true
schema:
type: string
format: date
description: Inicio del rango de fechas (incluido) en formato `YYYY-MM-DD`.
example: '2026-01-01T00:00:00.000Z'
- name: end_date
in: query
required: true
schema:
type: string
format: date
description: >-
Fin del rango de fechas (incluido) en formato `YYYY-MM-DD`. El rango
no debe superar los 90 días.
example: '2026-01-31T00:00:00.000Z'
- name: product
in: query
required: true
schema:
type: string
enum:
- agent
description: Producto cuyo consumo se consultará.
example: agent
- name: granularity
in: query
required: false
schema:
type: string
enum:
- daily
- monthly
description: >
Granularidad temporal para agrupar los resultados. Cuando se
especifica, cada fila incluye un campo `timestamp`.
Si se omite, los resultados se agregan para todo el rango de fechas.
- name: group_by
in: query
required: false
schema:
type: string
description: >
Lista de dimensiones, separadas por comas, por las que se agruparán
los resultados. Dimensiones compatibles:
- `user` — incluye `user_id` y `user_email` en cada fila
- `model_uid` — incluye `model_uid` en cada fila
- `ide` — incluye `ide` en cada fila
example: user,model_uid
- name: models
in: query
required: false
schema:
type: string
description: >-
Lista, separada por comas, de UID de modelos para filtrar los
resultados.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
Filtra los resultados para incluir solo usuarios de un grupo
específico. La clave de servicio debe tener acceso a este grupo.
- name: user_id
in: query
required: false
schema:
type: string
description: >-
Filtra los resultados para un usuario específico (UID de
autenticación).
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
description: Número máximo de filas que se devolverán por página.
- name: page_cursor
in: query
required: false
schema:
type: string
description: >-
Cursor opaco de `pagination.next_page_cursor` de una respuesta
anterior para obtener la página siguiente.
- name: If-None-Match
in: header
required: false
schema:
type: string
description: >-
Valor de ETag de una respuesta anterior. Si los datos no han
cambiado, el servidor devuelve `304 Not Modified`.
responses:
'200':
description: Datos de consumo devueltos correctamente.
headers:
ETag:
schema:
type: string
description: >-
Etiqueta de entidad para validar la caché. Pásala como
`If-None-Match` en solicitudes posteriores.
Cache-Control:
schema:
type: string
description: Directiva de caché (p. ej., `private, max-age=3600`).
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumptionResponse'
examples:
credits:
summary: >-
Equipo con facturación basada en créditos y granularidad
diaria
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: Equipo con facturación basada en 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: >-
Los datos no han cambiado desde el ETag proporcionado en
`If-None-Match`.
'400':
description: Parámetros de solicitud no vá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: La autenticación falló o los permisos son 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: >-
El cursor de página proporcionado no pertenece al equipo autenticado
ni al 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 no permitido (solo se admite `GET`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
Se superó el límite de tasa (10 solicitudes por hora por equipo).
Paginar una consulta anterior no cuenta para este límite.
headers:
Retry-After:
schema:
type: string
description: Tiempo de espera sugerido antes de volver a intentarlo.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
value:
error: rate limit exceeded
'503':
description: >-
El servicio de analítica no está disponible (p. ej., en despliegues
autohospedados).
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 filas de datos de consumo.
pagination:
type: object
properties:
next_page_cursor:
type:
- string
- 'null'
description: >
Cursor opaco para recuperar la siguiente página de resultados.
Pasa este valor como parámetro de consulta `page_cursor`
en una solicitud posterior. `null` cuando no hay más páginas.
Los cursores de página caducan al cabo de 24 horas.
metadata:
type: object
properties:
billing_strategy:
type: string
enum:
- CREDITS
- ACU
description: >
La estrategia de facturación del equipo autenticado. Determina
qué campos de `consumption` se completan:
- `CREDITS` — `prompt_credits` y `flex_credits`
- `ACU` — `billed_acus`
data_freshness:
type: string
format: date-time
description: >-
Marca de tiempo que indica cuándo se actualizaron por última vez
los datos subyacentes (truncada a la hora).
query_time_ms:
type: integer
format: int64
description: >-
Tiempo de ejecución de la consulta en el servidor, en
milisegundos.
team_id:
type: string
description: >-
El ID del equipo resuelto a partir de la clave de servicio
autenticada.
group_id:
type: string
description: >-
El ID del grupo al que se limitaron los resultados. Solo está
presente cuando se proporcionó `group_id`.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Mensaje de error legible por humanos.
ConsumptionRow:
type: object
required:
- consumption
properties:
timestamp:
type: string
description: >
Intervalo temporal de la fila. El formato depende de `granularity`:
`YYYY-MM-DD` para diario, `YYYY-MM` para mensual.
Solo está presente cuando se especifica `granularity`.
examples:
- '2026-05-01T00:00:00.000Z'
- 2026-05
user_id:
type: string
description: >-
Identificador de usuario (UID de autenticación). Solo está presente
cuando `group_by` incluye `user`.
user_email:
type: string
description: >-
Dirección de correo electrónico del usuario. Solo está presente
cuando `group_by` incluye `user`.
examples:
- alice@example.com
model_uid:
type: string
description: >-
Identificador del modelo. Solo está presente cuando `group_by`
incluye `model_uid`.
examples:
- claude-4-sonnet
ide:
type: string
description: Nombre del IDE. Solo está presente cuando `group_by` incluye `ide`.
examples:
- windsurf
- jetbrains
consumption:
$ref: '#/components/schemas/Consumption'
Consumption:
type: object
description: >-
Métricas de uso de la fila. Los campos se completan según la estrategia
de facturación del equipo.
properties:
prompt_credits:
type: integer
format: int64
description: Prompt credits consumidos (solo con facturación basada en créditos).
flex_credits:
type: integer
format: int64
description: Flex credits consumidos (solo con facturación basada en créditos).
billed_acus:
type: number
format: double
description: ACU facturados consumidos (solo con facturación basada en ACU).
message_count:
type: integer
format: int64
description: >-
Número de mensajes (eventos de facturación) en esta fila. Siempre se
completa independientemente de la estrategia de facturación.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Una clave de servicio con el permiso **Analytics Read**, pasada como
token Bearer en el encabezado `Authorization`.
Crea una clave de servicio en tu [configuración del
equipo](https://windsurf.com/team/settings), en la sección "Service
Keys".
````