API pública de facturación

Consulta el saldo de la cuenta, el uso de modelos y los costes desde tus herramientas de facturación

La API pública de facturación permite leer datos de facturación de Atlas Cloud desde scripts, paneles y sistemas financieros.

Base URL: https://api.atlascloud.ai/public/v1

Endpoints

Endpoint	Descripción
`GET /balance`	Saldo actual de la cuenta y resumen de créditos
`GET /model-usage`	Buckets diarios de uso de modelos
`GET /model-costs`	Buckets diarios de costes de modelos

Los esquemas completos están en la referencia de la API:

Autenticación

Envía una API Key de Atlas Cloud en el header Authorization:

Authorization: Bearer apikey-...

Crea claves en API Keys. La clave secreta empieza por apikey-.

Algunas respuestas y filtros usan un API Key public ID como ak_.... Este ID puede mostrarse en reportes de facturación, pero no es una credencial.

Permisos

/model-usage y /model-costs usan scope=self por defecto y devuelven el uso atribuido al usuario autenticado, incluidas las API Keys que posee.

Usa scope=account para consultar uso y costes de toda la cuenta. Este scope requiere account-level model billing read permission. /balance siempre usa account scope y requiere account balance read permission.

Los propietarios de cuentas personales pueden leer sus propios datos. En cuentas de equipo, usa un rol Account Admin o Finance.

Consultar Saldo

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

Los importes se devuelven como cadenas con seis decimales y moneda:

{
  "value": "125.500000",
  "currency": "usd"
}

Parámetros de Uso y Costes

start_date y end_date son fechas UTC obligatorias en formato YYYY-MM-DD. end_date es exclusivo y el rango máximo es de 180 días.

Parámetros comunes de /model-usage y /model-costs. Omitir group_by[] devuelve totales diarios:

Parámetro	Descripción
`start_date`	Fecha UTC de inicio inclusiva en formato `YYYY-MM-DD`
`end_date`	Fecha UTC de fin exclusiva en formato `YYYY-MM-DD`; el rango puede cubrir hasta 180 días
`scope`	`self` o `account`; por defecto `self`
`group_by[]`	Agrupación opcional. Conjuntos compatibles: `model_type`, `model`, `api_key`, o `model` más `api_key`; usa `group_by[]=model` para desglose por modelo
`model_types[]`	Repite con `text`, `image` o `video`
`model_ids[]`	Filtra por IDs de modelo; hasta 100 valores
`api_key_ids[]`	Filtra por public IDs `ak_...`; hasta 100 valores
`limit`	Filas por página, de 1 a 1000; por defecto 100
`page`	Cursor opaco recibido en `next_page`

Usa parámetros repetidos para arrays. Los valores separados por comas se rechazan.

Consultar Uso

La respuesta predeterminada devuelve totales diarios de uso.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

Consultar Costes

/model-costs acepta el mismo rango de fechas, scope, filtros, agrupación y paginación que /model-usage. Omitir group_by[] devuelve costes diarios totales.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

Paginación

Cuando has_more es true, envía next_page sin cambios como parámetro page. Trata el cursor como opaco y conserva los demás parámetros.

Errores y Límites

Los errores usan un envelope estable:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

Las respuestas limitadas devuelven 429 rate_limit_error y pueden incluir un header Retry-After.

En esta página