API de Límites de Gasto

La API de Límites de Gasto (Spend Limits API) te permite establecer un límite de gasto para cada miembro de Claude Enterprise, ver de dónde se hereda el límite de gasto de cada miembro y revisar o actuar sobre las solicitudes de los miembros para obtener un límite más alto.

Para informes de uso y costo por usuario y agrupados por intervalos de tiempo, consulta las API de Analytics.

Descripción general

La API expone ocho endpoints distribuidos en dos recursos:

Usa los endpoints de límites de gasto para responder "¿qué límite de gasto se aplica a cada miembro, de dónde proviene y qué tan cerca están de alcanzarlo?" y para establecer una anulación por usuario. Usa los endpoints de solicitudes de aumento del límite de gasto para procesar la cola de solicitudes enviadas por los miembros.

Requisitos previos

• Tu organización debe tener un plan Claude Enterprise.
• Los créditos de uso deben estar activados para tu organización. Tu propietario principal puede activarlos en la configuración de facturación de claude.ai.

Inicio rápido

Lista el límite de gasto mensual efectivo de cada miembro y su gasto acumulado en el período:

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Conceptos clave

La jerarquía de límites de gasto

Un límite de gasto efectivo (effective spend limit) se aplica al gasto de cada miembro y se resuelve a partir de una jerarquía de niveles de alcance. Cuando un miembro no tiene una anulación por usuario, hereda el límite de gasto configurado para su grupo (si tu organización usa límites basados en grupos), su nivel de asiento o el valor predeterminado de toda la organización. Un límite de gasto de grupo es un valor predeterminado por miembro: cada miembro que lo hereda se controla en función de su propio gasto, no de un presupuesto grupal compartido.

Leer GET /v1/organizations/spend_limits/effective devuelve todos los miembros actuales con su límite de gasto efectivo resuelto, de dónde se resolvió ese límite (source) y su gasto acumulado en el período. Establecer una anulación por usuario con POST /v1/organizations/spend_limits fija a un miembro a un límite de gasto específico independientemente de lo que heredaría de otro modo. Eliminar la anulación lo devuelve al límite de gasto heredado (o lo deja sin límite si no existe ninguno).

El campo source en la fila de cada miembro te indica desde qué nivel se resolvió su límite de gasto: user (una anulación por usuario), seat_tier, rbac_group u organization. Trata los tipos de alcance como un conjunto abierto; ignora los valores desconocidos en lugar de fallar.

Período

period es la ventana recurrente durante la cual se aplica el límite de gasto y se reinicia el gasto. Un límite de gasto se identifica por su par (scope, period). Actualmente monthly es el único período admitido; el gasto mensual se reinicia a las 00:00 UTC del primer día de cada mes calendario. Trata period como un conjunto abierto.

Montos y moneda

Todos los valores monetarios son cadenas en unidades menores de la moneda de facturación de la organización (centavos, para USD). Por ejemplo, "50000" representa 500.00 USD. Analízalo como decimal y divídelo por 100 para mostrar dólares; evita el punto flotante binario para valores grandes.

amount admite valores nulos. En la fila efectiva de un miembro, null significa ilimitado (sin límite de gasto) y "0" significa que el miembro no puede usar Claude más allá del uso incluido en su plan. En una fila de límite de gasto configurado (como la que devuelve GET /v1/organizations/spend_limits/{id}), null solo significa que no hay un límite de gasto numérico establecido; lee la fila efectiva del miembro para distinguir entre ilimitado y solo uso incluido.

period_to_date_spend es el gasto del miembro acumulado desde el inicio del period actual, en el mismo formato de unidades menores; puede incluir una parte fraccionaria (por ejemplo, "41280.125"). Puede aparecer como "0" si la lectura del gasto no está disponible temporalmente; trátalo como informativo, no transaccional.

Ciclo de vida de las solicitudes de aumento

Una solicitud de aumento del límite de gasto (spend limit increase request) se crea cuando un miembro hace clic en Request more usage (Solicitar más uso) en claude.ai. Las solicitudes no se crean a través de esta API. El status de una solicitud es uno de los siguientes:

Tanto approved como denied son estados terminales. Un miembro tiene como máximo una solicitud pending a la vez.

Aprobar con POST /v1/organizations/spend_limit_increase_requests/{id}/approve escribe la misma fila de límite de gasto por usuario que escribe POST /v1/organizations/spend_limits. Establecer un límite de gasto directamente no cambia el estado de una solicitud pendiente; usa el endpoint de aprobación para resolver una solicitud.

De forma predeterminada, Anthropic envía un correo electrónico al miembro cuando su solicitud es aprobada o denegada. Pasa suppress_notification: true al aprobar o denegar para suprimir ese correo (por ejemplo, cuando tu propio sistema notifica al miembro).

Control de versiones

Envía el encabezado anthropic-version en cada solicitud; consulta Versiones de la API para ver las versiones disponibles.

Límite de velocidad

Los ocho endpoints comparten un único "rate limit" (límite de velocidad) por organización de 60 solicitudes por minuto. Las solicitudes que superen el límite devuelven 429 Too Many Requests.

Paginación

GET /v1/organizations/spend_limits/effective y GET /v1/organizations/spend_limit_increase_requests se paginan con un cursor opaco. La primera solicitud devuelve hasta limit filas más un cursor next_page; pasa ese cursor sin modificar como el parámetro page en la siguiente solicitud, y repite hasta que next_page sea null.

No cambies los parámetros de consulta a mitad de la secuencia. Los cursores están vinculados a los filtros que los emitieron. Si cambias user_ids[], period[], status[] o actor_ids[] y pasas un cursor antiguo, obtendrás un 400 con "cursor does not match current query parameters". En su lugar, inicia una nueva secuencia desde la primera página.

Serialización de parámetros de lista

Los parámetros de lista usan notación de corchetes: repite el nombre del parámetro con [] para cada valor.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq

Respuestas de error

Las respuestas de error siguen la forma estándar documentada en Errores. Cita el request_id del cuerpo de la respuesta cuando contactes al soporte.

Límites de gasto

Listar el límite de gasto efectivo de cada miembro

GET /v1/organizations/spend_limits/effective devuelve una fila por cada miembro actual, que refleja el límite de gasto efectivo de cada miembro, su source en la jerarquía de alcances y su period_to_date_spend. Requiere el alcance read:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Listar límites de gasto efectivos en la referencia de la API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "jane@example.com",
        "deleted": false
      },
      "amount": "50000",
      "currency": "USD",
      "period": "monthly",
      "source": { "type": "seat_tier", "seat_tier": "enterprise_standard" },
      "spend_limit_id": "spl_01XyZaBcDeFgHiJkLmNoPq",
      "period_to_date_spend": "31402.5"
    }
  ],
  "next_page": "page_..."
}

Obtener un único límite de gasto

GET /v1/organizations/spend_limits/{spend_limit_id} devuelve un límite de gasto configurado por ID. Úsalo para inspeccionar la fila a la que hacía referencia un campo spend_limit_id. Requiere el alcance read:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Recuperar un límite de gasto en la referencia de la API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/spl_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Establecer una anulación por usuario

POST /v1/organizations/spend_limits establece una anulación del límite de gasto por usuario. Se trata de un upsert con clave (scope, period): establecer un límite para un usuario y período que ya tiene uno lo sobrescribe en su lugar. Este endpoint solo acepta scope.type: "user"; los valores predeterminados a nivel de nivel de asiento, grupo y organización se configuran en la configuración de claude.ai. Requiere el alcance write:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Crear un límite de gasto en la referencia de la API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "75000"}'

{
  "type": "spend_limit",
  "id": "spl_01RsTuVwXyZaBcDeFgHiJk",
  "created_at": "2026-05-11T10:02:44Z",
  "updated_at": "2026-05-11T10:02:44Z",
  "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
  "amount": "75000",
  "currency": "USD",
  "period": "monthly"
}

Eliminar una anulación por usuario

DELETE /v1/organizations/spend_limits/{spend_limit_id} elimina una anulación por usuario, tras lo cual el miembro vuelve a cualquier valor predeterminado heredado de nivel de asiento, grupo u organización. Las filas a nivel de nivel de asiento, grupo y organización no se pueden eliminar a través de este endpoint. Requiere el alcance write:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Eliminar un límite de gasto en la referencia de la API.

curl --request DELETE "https://api.anthropic.com/v1/organizations/spend_limits/spl_01RsTuVwXyZaBcDeFgHiJk" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Solicitudes de aumento del límite de gasto

Listar solicitudes de aumento

GET /v1/organizations/spend_limit_increase_requests lista las solicitudes, las más recientes primero. Filtra por status[] (pending, approved, denied) y actor_ids[]. La lista excluye las solicitudes cuyo solicitante ya no es miembro de la organización. Requiere el alcance read:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Listar solicitudes de aumento del límite de gasto en la referencia de la API.

curl --globoff "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Cada solicitud pendiente incluye un spend_summary en vivo que muestra el límite de gasto efectivo actual del solicitante y su gasto acumulado en el período, suficiente para decidir sin una consulta adicional.

Obtener una única solicitud de aumento

GET /v1/organizations/spend_limit_increase_requests/{id} devuelve una solicitud por ID. Requiere el alcance read:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Recuperar una solicitud de aumento del límite de gasto en la referencia de la API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01"

Aprobar una solicitud de aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/approve aprueba una solicitud pendiente: escribe un límite de gasto por usuario con el amount proporcionado por el administrador para el solicitante y cambia la solicitud a approved. La solicitud no incluye un monto solicitado; tú proporcionas el nuevo límite de gasto al aprobar. Requiere el alcance write:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Aprobar una solicitud de aumento del límite de gasto en la referencia de la API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/approve" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"amount": "75000", "suppress_notification": true}'

Denegar una solicitud de aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/deny deniega una solicitud pendiente. Es idempotente sobre denied: denegar una solicitud ya denegada devuelve 200 con el recurso existente. El endpoint rechaza un intento de denegar una solicitud ya aprobada para que la automatización pueda distinguir un reintento de una decisión contradictoria. Requiere el alcance write:spend_limits.

Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta Denegar una solicitud de aumento del límite de gasto en la referencia de la API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/deny" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --data '{"suppress_notification": true}'

Flujos de trabajo de ejemplo

Algunos de estos flujos de trabajo combinan la API de Límites de Gasto con los endpoints de costo de las API de Analytics. Los endpoints de costo de Analytics están diseñados para informes de gasto de toda la organización a lo largo de un rango de fechas. GET /spend_limits/effective devuelve el tope que se aplica actualmente a cada miembro. Comienza un barrido con Analytics para descubrir qué miembros revisar y luego lee sus topes actuales con /effective.

Los endpoints de Límites de Gasto requieren los alcances spend_limits y los endpoints de costo de Analytics requieren read:analytics; consulta las API de Analytics para saber cómo aprovisionar el acceso. Todos los valores monetarios en ambas son cadenas decimales en unidades menores (centavos). Ambas API paginan con un cursor opaco. Establece un limit explícito y recorre las páginas mediante next_page hasta que sea null para cubrir toda la organización.

Automatizar el flujo de revisión de solicitudes de aumento

Ejecuta un trabajo programado que obtenga las solicitudes pendientes, aplique la política de aprobación de tu organización y resuelva cada una.

1. Lista las solicitudes pendientes:

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

   Cada solicitud incluye el actor.user_id del solicitante y un spend_summary en vivo con su amount efectivo actual y su period_to_date_spend, suficiente para decidir sin una consulta adicional.

2. Aplica tu política. Por ejemplo, aprueba automáticamente cuando el amount actual del miembro esté por debajo de un umbral y deriva los topes más grandes a revisión manual.

3. Resuelve cada solicitud. Para aprobar, proporciona el nuevo tope:

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/{id}/approve" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"amount": "75000", "suppress_notification": true}'

   Para denegar, haz POST a .../{id}/deny en su lugar. Pasa suppress_notification: true cuando tu propio sistema notifique al solicitante.

Identificar miembros cercanos a su límite de gasto

Encuentra a los miembros que se acercan a su tope para poder aumentarlo antes de que queden bloqueados.

1. Obtén el gasto acumulado del mes de cada miembro desde la API de Analytics (una fila por miembro, el gasto más alto primero de forma predeterminada):

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY" \
     --header "anthropic-version: 2023-06-01"

   Cada fila incluye actor.user_id, actor.email y amount (el gasto del miembro en centavos). Recorre las páginas mediante next_page para cubrir toda la organización.

2. Para los miembros con mayor gasto (o todos los que superen un umbral en dólares), obtén los topes efectivos en lotes:

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01Ab...&user_ids[]=user_01Cd...&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

   Cada fila devuelve el tope como amount (null = ilimitado, "0" = solo uso incluido) junto con period_to_date_spend.

3. Para cada miembro con un tope positivo, calcula period_to_date_spend / amount y marca a aquellos que estén en tu umbral o por encima de él (por ejemplo, 80 por ciento). Trata un tope de "0" como si ya estuviera en el límite. No existe un filtro del lado del servidor para esta proporción.

4. Actúa sobre los miembros marcados: aumenta el tope con POST /v1/organizations/spend_limits, aprueba una solicitud de aumento pendiente si existe, o comunícate con el miembro.

Encontrar miembros con uso que cambia rápidamente

Identifica a los miembros cuyo gasto ha aumentado bruscamente de una semana a otra.

1. Obtén el costo diario por miembro de las últimas dos semanas desde la API de Analytics:

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY" \
     --header "anthropic-version: 2023-06-01"

   Con bucket_width establecido, cada miembro abarca una fila por cada día con uso; recorre las páginas mediante next_page para recopilar la serie completa de cada miembro.

2. Agrupa las filas por actor.user_id. Para cada miembro, suma los siete días más recientes y los siete días anteriores. Marca a los miembros cuya semana reciente supere la semana anterior por el múltiplo que elijas (por ejemplo, tres). El costo de los días recientes es provisional y puede revisarse al alza; para comparaciones repetibles, establece ending_at en o antes de un data_refreshed_at devuelto previamente (consulta Disponibilidad y actualización de los datos).

3. Actúa sobre los miembros marcados: ajusta el tope con POST /v1/organizations/spend_limits, o comunícate con ellos.

Aumentar temporalmente el límite de gasto de un miembro durante un incidente

Dale margen de trabajo a quien responde a un incidente mientras este esté abierto: aumenta su tope de gasto cuando comience el incidente y reviértelo después de que el incidente se cierre. Condiciona el aumento a tu sistema de gestión de incidentes, por ejemplo, exigiendo un ID de incidente activo con el miembro asignado a él.

1. Lee el tope actual del miembro y regístralo para la reversión:

   cURL

   

   curl --globoff "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01AbCdEfGh&period[]=monthly" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01"

2. Aumenta el tope:

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "500000", "period": "monthly"}'

3. Si quienes responden necesitan un acceso más amplio durante un incidente, aprovisiona previamente un grupo de respuesta a incidentes cuyo rol personalizado lo otorgue, y agrega al miembro durante ese tiempo:

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/rbac_groups/rbac_group_01UvWxYzAbCdEfGhIjKlMn/members" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data '{"user_id": "user_01AbCdEfGh"}'

   Consulta Gestión de usuarios para ver los endpoints de grupos.

4. Cuando tu sistema de incidentes marque el incidente como cerrado, revierte ambos cambios: restaura el límite de gasto que registraste en el paso 1 (o elimina la anulación con DELETE /v1/organizations/spend_limits/{spend_limit_id} si el miembro no tenía ninguna) y quita al miembro del grupo con DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}.

Preguntas frecuentes

¿Establecer un límite de gasto directamente resuelve la solicitud de aumento pendiente de un miembro?

No. POST /v1/organizations/spend_limits escribe la anulación pero deja intacta la solicitud pendiente. Usa POST /v1/organizations/spend_limit_increase_requests/{id}/approve para resolver la solicitud y escribir la anulación en una sola llamada.

¿Qué sucede cuando elimino una anulación por usuario?

El miembro vuelve a lo que heredaría de la jerarquía: el valor predeterminado de su grupo, nivel de asiento u organización. Si no existe ningún valor predeterminado en ningún nivel, el miembro queda sin límite.

¿Puedo establecer un valor predeterminado de nivel de asiento o de toda la organización a través de esta API?

No. Solo las anulaciones por usuario se pueden escribir a través de esta API. Los valores predeterminados a nivel de nivel de asiento, grupo y organización se configuran en la configuración de la organización en claude.ai.

¿Por qué period_to_date_spend a veces aparece como "0" para un miembro activo?

La lectura del gasto puede no estar disponible temporalmente, en cuyo caso el campo muestra "0" en lugar de generar un error. Trátalo como informativo.

Ver también