API de límites de gasto

La API de límites de gasto te permite establecer un límite de gasto para cada miembro de Claude Enterprise, consultar 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 costos por usuario y por intervalos de tiempo, consulta APIs de análisis.



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 de límite de gasto para gestionar 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"



Conceptos clave



La jerarquía de límites de gasto

Un límite de gasto efectivo se aplica al gasto de cada miembro, resuelto 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 contra su propio gasto, no contra un presupuesto grupal compartido.

Leer GET /v1/organizations/spend_limits/effective devuelve cada miembro actual 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 en 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 de 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; continúa con la ejecución ante 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



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 un decimal y divide entre 100 para mostrar dólares; evita el punto flotante binario para valores grandes.

amount es anulable. 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 configurada (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 mostrarse como "0" si la lectura de gasto no está disponible temporalmente; trátalo como informativo, no transaccional.



Ciclo de vida de las solicitudes de aumento

Una solicitud de aumento de límite de gasto 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 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 electrónico (por ejemplo, cuando tu propio sistema notifica al miembro).



Límite de velocidad

Los ocho endpoints comparten un único límite por organización de 60 solicitudes por minuto. Las solicitudes que superan el límite devuelven 429 Too Many Requests.



Paginación

GET /v1/organizations/spend_limits/effective y GET /v1/organizations/spend_limit_increase_requests están paginados con un cursor opaco. La primera solicitud devuelve hasta limit filas más un cursor next_page; pasa ese cursor sin cambios 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 error 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, reflejando 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 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"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "[email protected]",
        "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 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"



Establecer una anulación por usuario

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

Para obtener detalles completos de los parámetros y 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" \
  --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, después de 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 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"



Solicitudes de aumento de 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 esquemas de respuesta, consulta Listar solicitudes de aumento de límite de gasto en la referencia de la API.

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

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 esquemas de respuesta, consulta Recuperar una solicitud de aumento de 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"



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 el estado de 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 esquemas de respuesta, consulta Aprobar una solicitud de aumento de 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" \
  --data '{"amount": "75000", "suppress_notification": true}'



Denegar una solicitud de aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/deny deniega una solicitud pendiente. Idempotente en 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 en conflicto. Requiere el alcance write:spend_limits.

Para obtener detalles completos de los parámetros y esquemas de respuesta, consulta Denegar una solicitud de aumento de 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" \
  --data '{"suppress_notification": true}'



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 la solicitud pendiente intacta. 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 se pueden escribir anulaciones por usuario a través de esta API. Los valores predeterminados a nivel de nivel de asiento, grupo y organización se configuran en los ajustes de organización de claude.ai.



¿Por qué period_to_date_spend a veces se muestra como "0" para un miembro activo?

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



Consulta también