API de análisis de uso y costos

La API de análisis de uso y costos informa el uso histórico de tokens y el costo de tu organización, desglosados por las dimensiones que elijas, como el modelo, el espacio de trabajo, la clave de API o el usuario o la cuenta de servicio detrás de cada solicitud. Para las organizaciones de Claude Console, estos datos son similares a los que muestran las páginas Usage y Cost de Claude Console.

La API tiene dos endpoints:

• GET /v1/organizations/analytics/usage informa los recuentos de tokens y de solicitudes.
• GET /v1/organizations/analytics/cost informa el costo en USD.

La API de análisis de uso y costos está en beta. Envía en cada solicitud anthropic-beta: analytics-usage-cost-2026-08-24 como encabezado, junto con un encabezado anthropic-version. El SDK y la CLI ant envían ambos encabezados por ti y obtienen las páginas restantes a medida que lees los resultados, por lo que limit solo establece el tamaño de página.

Usa esta API para:

• Atribuir el gasto: Desglosa el costo y el uso de tokens por espacio de trabajo, clave de API, modelo, nivel de servicio o la identidad que realizó cada solicitud.
• Encontrar a los principales consumidores: Clasifica los resultados por tokens, solicitudes o costo para responder preguntas como “¿qué claves de API gastan más este mes?”
• Crear series temporales: Divide los resultados en intervalos diarios, por hora o por minuto para paneles e informes financieros.
• Integrar una sola vez: Los mismos endpoints, parámetros y campos de respuesta sirven para organizaciones de Claude Console y Claude Enterprise.

Inicio rápido

Obtén el uso diario de tokens de la primera semana de septiembre, con una fila por cada modelo y día:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=10,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

La respuesta tiene una fila por cada modelo y día con uso, con el mayor total_tokens primero. Este ejemplo muestra una sola fila:

{
  "data": [
    {
      "starting_at": "2026-09-03T00:00:00Z",
      "ending_at": "2026-09-04T00:00:00Z",
      "group": {
        "product": null,
        "model": "claude-sonnet-5",
        "context_window": null,
        "inference_geo": null,
        "speed": null,
        "slack_channel_id": null,
        "claude_tag_category": null,
        "claude_tag_user_id": null,
        "rbac_group_id": null,
        "workspace_id": null,
        "service_tier": null,
        "user_profile_id": null,
        "agent_id": null,
        "environment_id": null,
        "deployment_id": null,
        "session_id": null,
        "actor": null,
        "actor_type": null,
        "api_key_id": null
      },
      "usage": {
        "uncached_input_tokens": 1284500,
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 215300
        },
        "cache_read_input_tokens": 3200000,
        "output_tokens": 891000,
        "total_tokens": 5590800,
        "server_tool_use": {
          "web_search_requests": 12
        },
        "requests": 4210
      }
    }
  ],
  "has_more": true,
  "next_page": "page_V2mQ4dkt9HcbX3pLr...",
  "data_refreshed_at": "2026-09-18T16:02:11Z"
}

Cómo se estructuran los resultados

• Cada fila tiene tres partes: starting_at y ending_at indican el período que cubre la fila, group contiene todas las dimensiones y usage (o cost en el endpoint de costos) contiene las métricas.
• Las dimensiones son nulas a menos que se agrupen: Una dimensión en group es null a menos que la incluyas en group_by[]. Una dimensión agrupada también es null en las filas que no tienen valor para ella, como model en el uso de ejecución de código. group_by[] admite hasta cinco dimensiones.
• Una fila por cada combinación: Cada fila es una combinación de las dimensiones agrupadas, y cada combinación que tiene uso o costo aparece exactamente una vez en las páginas de una consulta. Sin group_by[] y sin time_bucket_width, la respuesta es una sola fila que totaliza todo el rango.
• Los intervalos de tiempo son opcionales: Establece time_bucket_width en 1m, 1h o 1d para dividir cada combinación por intervalo UTC; entonces, starting_at y ending_at de cada fila son los límites de su intervalo. Los intervalos sin uso ni costo no producen filas.
• Clasificadas de forma predeterminada: Las filas se ordenan según la métrica de order_by en todo el rango, de mayor a menor de forma predeterminada (order=asc invierte el orden). Para construir una serie temporal, establece time_bucket_width y order_by=time. Las filas se devuelven entonces un intervalo de tiempo tras otro, con el intervalo más reciente primero de forma predeterminada (order=asc coloca el más antiguo primero), y con las filas más grandes primero dentro de cada intervalo. Rellena los intervalos vacíos con ceros.
• Los filtros funcionan junto con la agrupación: La mayoría de las dimensiones por las que puedes agrupar tienen un filtro de lista correspondiente en notación de corchetes, como models[]=claude-opus-5-5. Repite el parámetro para pasar varios valores, hasta 100. Los valores múltiples para el mismo filtro se combinan con OR, y los distintos filtros se combinan con AND. Los filtros y group_by[] son independientes; puedes filtrar por cualquier dimensión con o sin agrupar por ella, o al revés.

Dimensiones como model y actor se aplican a todas las organizaciones. Algunas, como api_key_id, se aplican solo a organizaciones de Claude Console, y otras, como slack_channel_id, se aplican solo a organizaciones de Claude Enterprise. Una dimensión que no se aplica a tu organización es null en todas las filas y su filtro no coincide con nada; la excepción es rbac_group_id, que en su lugar devuelve un error cuando los equipos no están disponibles para tu organización. La referencia de la API de uso y costos enumera todas las dimensiones, filtros y valores.

Actores

La dimensión actor indica a quién se atribuye una solicitud: un usuario, una cuenta de servicio, una identidad de nube federada (un principal de AWS o Google Cloud, para organizaciones que acceden a Claude a través de su plataforma en la nube) o, cuando ninguno de ellos está detrás de la solicitud, la propia clave de API. Cuando agrupas por actor, el actor de cada fila es un objeto cuyo type indica de qué tipo es. El uso que no se puede atribuir a ninguna identidad tiene actor: null.

Las claves personales y las claves de cuenta de servicio actúan como el usuario o la cuenta de servicio a los que están vinculadas, por lo que sus solicitudes muestran esa identidad como actor y la clave en api_key_id. Las claves de espacio de trabajo heredadas no están vinculadas a una identidad, por lo que la clave aparece como actor y también como api_key_id. La excepción es la clave que crea Claude Code cuando un miembro inicia sesión con su cuenta de Claude Console: reside en el espacio de trabajo de Claude Code, y su uso se atribuye a ese miembro. Las solicitudes realizadas sin una clave de API, como desde Claude Console o con un token de Workload Identity Federation, tienen api_key_id: null; el actor de una carga de trabajo federada es su cuenta de servicio. Para incluir el uso sin clave de API en un filtro api_key_ids[], agrega una entrada vacía: api_key_ids[]=.

Los filtros api_key_ids[] y actor_ids[] responden a preguntas diferentes. api_key_ids[]=apikey_... coincide con todas las solicitudes que autenticó la clave, sin importar a quién se atribuyan. actor_ids[]=apikey_... coincide solo con las solicitudes atribuidas a la propia clave.

Endpoint de uso

GET /v1/organizations/analytics/usage devuelve recuentos de tokens por tipo. order_by acepta total_tokens (el valor predeterminado), output_tokens, uncached_input_tokens, requests o time.

Por ejemplo, para ver una semana de uso de un espacio de trabajo y una clave de API, desglosado por nivel de servicio (una fila por cada nivel, que cubre toda la semana):

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    api_key_ids=["apikey_01Rj2N8SVvo6BePZj99NhmiT"],
    group_by=["service_tier"],
)

for row in rows:
    print(f"{row.group.service_tier}: {row.usage.total_tokens}")

Para buscar los ID de claves de API y de espacios de trabajo, usa los endpoints List API Keys y List Workspaces o Claude Console.

Para averiguar qué usuarios, cuentas de servicio y claves de API realizaron más solicitudes en un mes:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["actor"],
    order_by="requests",
    limit=25,
)

for row in rows:
    print(f"{row.group.actor}: {row.usage.requests}")

Endpoint de costos

GET /v1/organizations/analytics/cost acepta los mismos filtros, dimensiones e intervalos de tiempo que el endpoint /usage. El objeto cost de cada fila contiene amount (el costo después de descuentos y antes de aplicar cualquier crédito), list_amount (el costo a precios de lista), currency (siempre "USD") y requests. Los importes son cadenas decimales en centavos con seis decimales: "41280.000000" equivale a $412.80 USD. order_by acepta amount (el valor predeterminado), list_amount o time.

Existen dos dimensiones adicionales solo en este endpoint que no cuentan para el límite de cinco dimensiones: group_by[]=cost_type divide cada fila en una fila por cada tipo de costo, y group_by[]=token_type divide el costo de tokens en una fila por cada tipo de token. limit tampoco se aplica a estas dos dimensiones, por lo que una página puede contener más de limit filas. Por ejemplo, el costo por modelo, tipo de costo y tipo de token durante un mes:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    group_by=["model", "cost_type", "token_type"],
)

for row in rows:
    print(
        f"{row.group.model} {row.group.cost_type} {row.group.token_type}: {row.cost.amount}"
    )

Para cada modelo, la respuesta tiene cinco filas de tokens (una por cada tipo de token) más una fila para cada uno de web_search, code_execution y session_usage. Una de esas filas:

{
  "starting_at": "2026-09-01T00:00:00Z",
  "ending_at": "2026-10-01T00:00:00Z",
  "group": {
    "model": "claude-opus-5",
    ...,
    "cost_type": "tokens",
    "token_type": "cache_read_input_tokens"
  },
  "cost": {
    "currency": "USD",
    "amount": "41280.000000",
    "list_amount": "51600.000000",
    "requests": null
  }
}

El objeto group incluye todas las dimensiones y aquí está abreviado. Cuando se especifica group_by[]=cost_type o token_type, requests es null en todas las filas.

Rangos de fechas e intervalos de tiempo

• Las marcas de tiempo siguen RFC 3339 con un desplazamiento UTC, por ejemplo 2026-09-01T00:00:00Z. starting_at es inclusivo y ending_at es exclusivo.
• starting_at debe ser el 1 de enero de 2026 o posterior, y estar dentro de los últimos 365 días. Una solicitud puede abarcar como máximo 31 días; ending_at tiene como valor predeterminado 31 días después de starting_at o la hora actual, lo que ocurra primero.
• ending_at es obligatorio siempre que se establezca time_bucket_width, y con time_bucket_width=1m una solicitud puede abarcar como máximo 24 horas.
• Ambos extremos del rango se redondean hacia abajo a un límite de intervalo UTC, o a la hora cuando no se establece time_bucket_width. Por ejemplo, con time_bucket_width=1h, un starting_at de 2026-09-01T10:43:00Z se trata como 2026-09-01T10:00:00Z y un ending_at de 2026-09-01T15:43:00Z como 2026-09-01T15:00:00Z, por lo que la respuesta cubre de 10:00 a 15:00 UTC.

Actualización de los datos

Cada respuesta incluye una marca de tiempo data_refreshed_at, y el uso posterior a ese momento falta o es parcial. Cuando todavía no hay datos disponibles para ninguna parte del rango solicitado, data_refreshed_at es null y data está vacío. Los datos suelen actualizarse dentro de las 4 horas posteriores al uso subyacente y pueden tardar hasta 24 horas. Los valores pueden revisarse a medida que llegan eventos tardíos y se ejecuta la conciliación, hasta aproximadamente 7 días después del final del mes calendario. Por ejemplo, los valores del 1 de octubre pueden cambiar hasta aproximadamente el 7 de noviembre. Para obtener resultados estables en llamadas repetidas, establece ending_at en un data_refreshed_at que ya hayas visto o antes; para obtener totales finales, consulta solo meses que hayan terminado hace al menos 7 días. Cada página de una consulta paginada lee la misma instantánea de datos, por lo que data_refreshed_at es idéntico en todas las páginas.

Migrar desde la API de uso y costos

Esta sección es para organizaciones de Claude Console que llaman a la API de uso y costos heredada (/v1/organizations/usage_report/messages y /v1/organizations/cost_report). Tu clave de API de administrador, el encabezado anthropic-version, starting_at y ending_at, los valores de ancho de intervalo (1m, 1h, 1d), la notación de corchetes, los nombres de los campos de paginación y los nombres de los campos de tokens y costos se mantienen. Lo que cambia:

Para reproducir el informe diario heredado, solicita time_bucket_width=1d con el mismo group_by[], recorre las páginas con limit=1000 y luego agrupa las filas por starting_at y rellena los días faltantes con ceros. Agrega order_by=time&order=asc para obtener los días en orden. Uso diario por modelo durante 1 semana, antes:

curl --globoff "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-09-01T00:00:00Z&\
ending_at=2026-09-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

y después:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=["model"],
    limit=1000,
)

for row in rows:
    print(f"{row.starting_at} {row.group.model}: {row.usage.total_tokens}")

Costo diario por espacio de trabajo, modelo, nivel de servicio, ventana de contexto y geografía de inferencia, dividido por tipo de costo y tipo de token:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    group_by=[
        "workspace_id",
        "model",
        "service_tier",
        "context_window",
        "inference_geo",
        "cost_type",
        "token_type",
    ],
    limit=1000,
)

for row in rows:
    group = row.group
    print(
        f"{row.starting_at} {group.workspace_id} {group.model} {group.service_tier} "
        f"{group.context_window} {group.inference_geo} {group.cost_type} {group.token_type}: "
        f"{row.cost.amount}"
    )

Migrar desde los informes de uso y costos de Claude Enterprise

Esta sección es para organizaciones de Claude Enterprise que llaman a los endpoints de informes usage_report, cost_report, user_usage_report y user_cost_report de la Claude Enterprise Analytics API bajo /v1/organizations/analytics/. Esos endpoints son heredados y siguen siendo compatibles. Migra a /analytics/usage y /analytics/cost cuando quieras alguna de las siguientes ventajas:

• Todos los grupos de cada intervalo de tiempo, en lugar de los 100 grupos principales de cada intervalo
• Agrupación por actor o actor_type junto con otras dimensiones, tanto en uso como en costos
• Filas clasificadas según la métrica que elijas en todo el rango, u ordenadas por intervalo de tiempo
• Una sola integración que también sirve para organizaciones de Claude Console

Se mantienen tu clave, la fecha más antigua, el período retrospectivo de 365 días y el rango de 31 días, los nombres y valores de filtros y dimensiones (excepto user_ids[] y el valor de producto de Claude Tag), los campos de actor de usuario, los campos de métricas e importes, data_refreshed_at, las reglas del cursor y el límite de velocidad a nivel de organización. El único encabezado nuevo es el encabezado beta analytics-usage-cost-2026-08-24. Lo que cambia:

Costo por usuario durante un mes, antes:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.user_cost_report.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    limit=100,
)

for row in rows:
    print(f"{row.actor.user_id}: {row.amount}")

y después, agregando un desglose por producto:

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.cost.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-10-01T00:00:00Z",
    actor_types=["user_actor"],
    group_by=["actor", "product"],
    limit=100,
)

for row in rows:
    actor = row.group.actor
    if actor is not None and actor.type == "user_actor":
        print(f"{actor.user_id} {row.group.product}: {row.cost.amount}")

Preguntas frecuentes

¿Cómo se representa el espacio de trabajo predeterminado?

El espacio de trabajo predeterminado de una organización de Claude Console tiene su propio ID wrkspc_, como cualquier otro espacio de trabajo. Las filas del espacio de trabajo predeterminado tienen ese ID en workspace_id, y puedes filtrar por él con workspace_ids[]. List Workspaces omite el espacio de trabajo predeterminado a menos que pases include_default=true. Para comprobar si un workspace_id desconocido es el espacio de trabajo predeterminado, pásalo a Get Workspace: el espacio de trabajo predeterminado devuelve "name": "Default".

¿Cómo obtengo el costo por usuario de Claude Code?

Llama al endpoint de costos con products[]=claude_code&group_by[]=actor. Las organizaciones de Claude Console también pueden usar la Claude Code Analytics API, que informa la actividad de Claude Code por usuario y el costo estimado.

Consulta también

• API de uso y costos (heredada)
• APIs de analítica: qué API de analítica y qué tipo de clave necesita tu organización
• Claude Code Analytics API
• Referencia de la Admin API
• Precios