Saltar al contenido principal
GET
/
api
/
v2alpha
/
analytics
/
consumption
Obtener analíticas de consumo
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/consumption \
  --header 'Authorization: Bearer <token>'
{
  "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"
  }
}
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 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 <your_service_key>
La clave de servicio debe tener el permiso Analytics Read. Crea una en tu Team Settings, en “Service Keys”.

​
Estrategia de facturación

La estructura de la respuesta depende de la estrategia de facturación de tu equipo:
EstrategiaCampos completadosDescripción
CREDITSprompt_credits, flex_creditsEquipos Standard de Enterprise SaaS
ACUbilled_acusEquipos 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.

Autorizaciones

​
Authorization
string
header
requerido

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, en la sección "Service Keys".

Encabezados

​
If-None-Match
string

Valor de ETag de una respuesta anterior. Si los datos no han cambiado, el servidor devuelve 304 Not Modified.

Parámetros de consulta

​
start_date
string<date>
requerido

Inicio del rango de fechas (incluido) en formato YYYY-MM-DD.

​
end_date
string<date>
requerido

Fin del rango de fechas (incluido) en formato YYYY-MM-DD. El rango no debe superar los 90 días.

​
product
enum<string>
requerido

Producto cuyo consumo se consultará.

Opciones disponibles:
agent
​
granularity
enum<string>

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.

Opciones disponibles:
daily,
monthly
​
group_by
string

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

Lista, separada por comas, de UID de modelos para filtrar los resultados.

​
group_id
string

Filtra los resultados para incluir solo usuarios de un grupo específico. La clave de servicio debe tener acceso a este grupo.

​
user_id
string

Filtra los resultados para un usuario específico (UID de autenticación).

​
page_size
integer
predeterminado:1000

Número máximo de filas que se devolverán por página.

Rango requerido: 1 <= x <= 10000
​
page_cursor
string

Cursor opaco de pagination.next_page_cursor de una respuesta anterior para obtener la página siguiente.

Respuesta

Datos de consumo devueltos correctamente.

​
data
object[]
requerido

Array de filas de datos de consumo.

​
pagination
object
requerido
​
metadata
object
requerido