Conceptos básicos de seguimiento de uso y costes

9 ejemplos para empezar con el seguimiento de uso y costes: 6 básicos y 3 intermedios.

Prerrequisitos

• Instala el SDK: pip install anthropic.
• Genera una clave de API de administrador desde la Consola de Claude (una clave de API normal no puede llamar a los puntos de conexión de la API de administrador).
• Configura ANTHROPIC_ADMIN_KEY como una variable de entorno en lugar de codificarla en tu script.

Ejemplos básicos

1. Obtener un informe de uso

Obtén el uso de tokens sin procesar de los últimos 7 días sin agrupar.

import anthropic
from datetime import datetime, timedelta, timezone
 
client = anthropic.Anthropic(api_key=None)  # recoge ANTHROPIC_ADMIN_KEY
 
start = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
 
report = client.beta.usage.report(starting_at=start)
 
for bucket in report.data:
    print(bucket.uncached_input_tokens, bucket.output_tokens)

• report() devuelve registros de uso agrupados por tiempo, no un total plano.
• Cada registro separa uncached_input_tokens, cached_input_tokens, cache_creation_input_tokens y output_tokens.
• Sin group_by, los resultados se agregan en toda tu organización.

2. Obtener un informe de costes

Obtén la vista en dólares de la misma ventana.

import anthropic
 
client = anthropic.Anthropic()
 
cost = client.beta.cost.report(starting_at="2026-06-01T00:00:00Z")
 
for bucket in cost.data:
    print(bucket.amount, bucket.currency)

• El punto de conexión de costes refleja la forma del punto de conexión de uso, pero devuelve importes en dólares en lugar de recuentos de tokens.
• El coste se deriva del uso según los precios actuales de la plataforma, no de una entrada manual separada.
• Utiliza el punto de conexión de costes cuando solo necesites un total en dólares; utiliza el uso cuando necesites explicar por qué.

3. Filtrar por un solo espacio de trabajo

Reduce un informe a un solo ID de espacio de trabajo.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    workspace_ids=["wksp_01abc123"],
)

• workspace_ids acepta una lista, por lo que puedes filtrar por uno o varios espacios de trabajo en una sola llamada.
• Encuentra los IDs de espacio de trabajo en la Consola, en la configuración de la Organización, o listando los espacios de trabajo con la API de administrador.
• Omitir este filtro devuelve el uso de todos los espacios de trabajo a los que tienes acceso.

4. Agrupar el uso por espacio de trabajo

Ve el uso de cada espacio de trabajo uno al lado del otro, en lugar de filtrar por uno solo.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    group_by=["workspace_id"],
)
 
for bucket in report.data:
    print(bucket.workspace_id, bucket.output_tokens)

• group_by devuelve una fila por cada valor único de la clave de agrupación, similar a GROUP BY en SQL.
• Agrupar por workspace_id es la forma más rápida de ver qué equipo está impulsando el uso.
• Puedes combinar varias claves de agrupación en una sola lista, por ejemplo ["workspace_id", "model"].

5. Establecer un rango de tiempo con una fecha de finalización

Limita un informe a una ventana específica en lugar de "todo desde una fecha de inicio".

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    ending_at="2026-06-30T23:59:59Z",
)

• ending_at es opcional; omitirlo por defecto es "ahora".
• Ambas marcas de tiempo son ISO 8601 y se interpretan en UTC.
• Una ventana delimitada es lo que deseas para un informe mensual que no debería cambiar a medida que pasan los nuevos días.

6. Elegir una granularidad de cubo de tiempo

Controla si los resultados se devuelven por día, por hora o como un total sumado.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    ending_at="2026-06-08T00:00:00Z",
    bucket_width="1d",
)
 
for bucket in report.data:
    print(bucket.starting_at, bucket.output_tokens)

• bucket_width controla cómo se divide el uso por tiempo dentro de tu ventana, por ejemplo "1h" o "1d".
• Un ancho de cubo más fino te da una línea de tendencia; uno más grueso te da una única cifra resumen.
• Elige el ancho para que coincida con cómo planeas graficar los datos, no solo la opción más amplia disponible.

Relacionado: Cómo los modelos de API de administración de uso y costes reflejan tu gasto - el modelo de cubo de tokens detrás de estos campos

Ejemplos intermedios

7. Combinar filtro de espacio de trabajo con agrupación por modelo

Responde "¿qué modelos está utilizando este espacio de trabajo y cuánto cuestan?" en una sola llamada.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    workspace_ids=["wksp_01abc123"],
    group_by=["model"],
)
 
for bucket in report.data:
    total_input = bucket.uncached_input_tokens + bucket.cached_input_tokens
    print(bucket.model, total_input, bucket.output_tokens)

• Los filtros (workspace_ids) y la agrupación (group_by) se componen libremente en la misma solicitud.
• Sumar uncached_input_tokens y cached_input_tokens te da el volumen total de entrada, mientras que mantenerlos visibles por separado preserva la historia de costes.
• Este patrón es el punto de partida para un informe de costes por espacio de trabajo y por modelo.

8. Paginación a través de un informe grande

Recorre cada página de un informe que abarca más datos de los que caben en una sola respuesta.

import anthropic
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-01-01T00:00:00Z",
    group_by=["api_key_id", "model"],
)
 
all_buckets = list(report.data)
while report.has_next_page():
    report = report.get_next_page()
    all_buckets.extend(report.data)
 
print(len(all_buckets), "cubos de uso obtenidos")

• Los rangos de fechas amplios combinados con claves group_by detalladas pueden producir muchas filas, por lo que la paginación es común en la práctica.
• El objeto de página del SDK expone has_next_page() y get_next_page() para que no tengas que implementar la lógica del cursor manualmente.
• Acumula siempre en tu propia lista o base de datos; los objetos de página del SDK no están pensados para conservarse indefinidamente.

9. Consolidar costes por tipo de token

Calcula un total de costes por tipo de token a partir de un solo informe, el primer paso hacia un panel de control real.

import anthropic
from collections import defaultdict
 
client = anthropic.Anthropic()
 
report = client.beta.usage.report(
    starting_at="2026-06-01T00:00:00Z",
    group_by=["model"],
)
 
totals = defaultdict(int)
for bucket in report.data:
    totals["uncached_input"] += bucket.uncached_input_tokens
    totals["cached_input"] += bucket.cached_input_tokens
    totals["cache_creation"] += bucket.cache_creation_input_tokens
    totals["output"] += bucket.output_tokens
 
for token_type, count in totals.items():
    print(token_type, count)

• defaultdict(int) evita KeyErrors mientras acumula recuentos en muchos cubos.
• Esta es la forma bruta que necesita un panel de control financiero antes de aplicar precios por tipo de token.
• Mantener los cuatro tipos de tokens separados aquí, en lugar de sumarlos en un solo número, es lo que preserva la capacidad de explicar el total más tarde.

Relacionado: Creación de un panel de control de costes a partir de desgloses de tokens no cacheados, cacheados y de salida - el panel de control completo al que conduce este patrón | Consulta de uso por clave de API y espacio de trabajo con la API de administración - consultas más específicas, de clave única y de espacio de trabajo único

Versiones de la pila: Escrito contra la línea de modelos de Claude actual hasta aproximadamente junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5, y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, los precios y las versiones del SDK cambian rápidamente: verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.