API de límites de velocidad
Lee programáticamente los límites de velocidad de la API de tu organización y establece los límites de velocidad de los espacios de trabajo con la API de límites de velocidad.
La API de límites de velocidad proporciona acceso programático a los “rate limits” (límites de velocidad) configurados para tu organización y sus espacios de trabajo. Esta es la misma información que se muestra en la página Límites de frecuencia en la Claude Console. También puedes usarla para establecer y borrar los límites de velocidad de un espacio de trabajo.
Usa esta API para:
- Mantener sincronizados los gateways y proxies: Lee tus límites actuales al iniciar y de forma programada en lugar de codificar valores fijos que quedan desactualizados cuando Anthropic los ajusta.
- Revisar el margen restante: Compara el uso pasado de la API de análisis de uso y costos con tus límites configurados.
- Auditar la configuración de los espacios de trabajo: Verifica que las anulaciones de los espacios de trabajo coincidan con lo que espera tu automatización de aprovisionamiento.
- Administra los límites de los espacios de trabajo desde el código: Establece y borra los límites de cada espacio de trabajo desde tu automatización de aprovisionamiento en lugar de editarlos en la Console.
El cliente predeterminado del SDK y la CLI leen la clave de API de administrador desde la variable de entorno ANTHROPIC_API_KEY. El SDK expone estos endpoints como client.organization.rate_limits y client.organization.workspaces.rate_limits. Los comentarios de cada ejemplo de listado indican si obtiene más páginas o lee solo la primera.
Inicio rápido
Lista los límites de velocidad configurados para tu organización:
client = anthropic.Anthropic()
rate_limits = client.organization.rate_limits.list()
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value}")Límites de velocidad de la organización
El endpoint /v1/organizations/rate_limits devuelve los límites de velocidad aplicados a nivel de organización para la API de Messages y sus recursos de soporte. No se incluyen los límites de otros productos, como Claude Managed Agents.
Conceptos clave
- Grupos de límites de velocidad: Cada entrada de la respuesta representa un grupo de límites de velocidad. Los límites de velocidad de los modelos se agrupan de modo que varias versiones de modelos comparten un único conjunto de límites. Los demás grupos cubren la Message Batches API y la herramienta de búsqueda web.
- Objeto
group: Presente en cada entrada, identifica el grupo de límites de velocidad al que se aplica la entrada. Siempre tienetype, que es uno de los valores degroup_type, eid, un identificador opaco con el prefijorlg_. En las entradasmodel_grouptambién tienedisplay_name, la etiqueta actual de Anthropic para el grupo, comoClaude Sonnet 4.x. La etiqueta es solo para visualización y puede cambiar. Los demás tipos de grupo no tienendisplay_name. - El
iddentro degroup: Un grupo tiene el mismoiden todas las organizaciones y en todas las anulaciones de espacios de trabajo, y nunca cambia. Úsalo para hacer coincidir entradas entre organizaciones o con tu propio catálogo. Elidpropio de la entrada difiere en cada organización, ymodelscambia cuando Anthropic mueve un modelo entre grupos. Ninguno de los dos es una clave estable para el grupo. group_type: El parámetro de consulta que restringe la lista a un tipo de grupo. Consulta Filtrar por tipo de grupo para ver los valores.- Lista
models: Para las entradasmodel_group, el campomodelsenumera cada ID de modelo y alias que cuenta para los límites de ese grupo. Usa esta lista para buscar a qué grupo pertenece cualquier cadena de modelo. Para otros tipos de grupo,modelsesnull. - Lista
limits: Cada grupo contiene una lista de pares{type, value}. El campotypeidentifica el limitador (comorequests_per_minute,input_tokens_per_minuteuoutput_tokens_per_minute) yvaluees el límite configurado. Consulta Límites de velocidad para saber cómo se mide y aplica cada limitador. sourceen los límites de espacios de trabajo: En el endpoint de espacios de trabajo, cada valor de límite también incluyesource, que indica de dónde provienevalue:{"type": "workspace"}para una anulación almacenada en el espacio de trabajo, o{"type": "organization"}para un valor heredado de la organización. De forma predeterminada, el endpoint de espacios de trabajo devuelve solo anulaciones, por lo quesource.typesiempre esworkspaceallí; los valores heredados aparecen cuando pasasinclude_inherited=true. Consulta Límites de velocidad del espacio de trabajo.
Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de límites de velocidad de la organizaciónVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver..
Listar todos los límites de velocidad de la organización
client = anthropic.Anthropic()
rate_limits = client.organization.rate_limits.list()
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value}"){
"data": [
{
"id": "rlt_01NwFawrTvAijwqn8AjKVBPS",
"type": "rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Hq7YkP3mZ9dTwRx4cVbN2s",
"display_name": "Claude Opus 5.5"
},
"models": ["claude-opus-5-5"],
"limits": [
{ "type": "requests_per_minute", "value": 4000 },
{ "type": "input_tokens_per_minute", "value": 10000000 },
{ "type": "output_tokens_per_minute", "value": 800000 }
]
},
{
"id": "rlt_016qriyigbdebqkzhMujdHkX",
"type": "rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Kd5wMv8nSq2LcXy6tRfJ4b",
"display_name": "Claude Opus 4.x"
},
"models": [
"claude-opus-4-5",
"claude-opus-4-5-20251101",
"claude-opus-4-6",
"claude-opus-4-7",
"claude-opus-4-8"
],
"limits": [
{ "type": "requests_per_minute", "value": 4000 },
{ "type": "input_tokens_per_minute", "value": 10000000 },
{ "type": "output_tokens_per_minute", "value": 800000 }
]
},
{
"id": "rlt_01EyY8kq14eviKJPgepbgBH4",
"type": "rate_limit",
"group": { "type": "batch", "id": "rlg_01Wn3pBz6kCg9vHtQ7mLxD5a" },
"models": null,
"limits": [{ "type": "enqueued_batch_requests", "value": 500000 }]
}
],
"next_page": null
}Buscar los límites de un modelo específico
Pasa cualquier ID de modelo o alias como parámetro de consulta model para devolver solo la entrada que lo contiene:
client = anthropic.Anthropic()
rate_limits = client.organization.rate_limits.list(model="claude-opus-5-5")
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value}")Si la cadena de modelo no coincide con ningún grupo, el endpoint devuelve un error 404. Cualquier modelo al que tenga acceso tu organización coincide con su grupo. El parámetro model solo es compatible con el endpoint de la organización; el endpoint del espacio de trabajo no lo acepta.
Límites de velocidad del espacio de trabajo
El endpoint /v1/organizations/workspaces/{workspace_id}/rate_limits devuelve las anulaciones de límites de velocidad configuradas para un solo espacio de trabajo. Para ver también los valores que hereda el espacio de trabajo, pasa include_inherited=true (consulta Incluir valores heredados). Para cambiar las anulaciones, consulta Establecer límites de velocidad del espacio de trabajo.
De forma predeterminada, la respuesta solo incluye anulaciones, por lo que todo lo que falte en ella se hereda de la organización:
- Un grupo que no aparece en
datano tiene ninguna anulación en el espacio de trabajo. El espacio de trabajo hereda los límites a nivel de organización para ese grupo (no es ilimitado). - Dentro de un grupo presente, un tipo de limitador que no aparece en
limits[]no tiene anulación en el espacio de trabajo para ese limitador. El espacio de trabajo hereda el valor de la organización para él. - Para cada limitador presente,
org_limites el valor a nivel de organización para el mismo limitador, onullsi la organización no tiene un límite configurado para ese tipo de limitador, ysourcees{"type": "workspace"}.
Para obtener detalles completos de los parámetros y los esquemas de respuesta, consulta la referencia de la API de límites de velocidad del espacio de trabajoVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver..
client = anthropic.Anthropic()
rate_limits = client.organization.workspaces.rate_limits.list(
"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value}"){
"data": [
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_01NwFawrTvAijwqn8AjKVBPS",
"type": "workspace_rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Hq7YkP3mZ9dTwRx4cVbN2s",
"display_name": "Claude Opus 5.5"
},
"models": ["claude-opus-5-5"],
"limits": [
{
"type": "requests_per_minute",
"value": 1000,
"org_limit": 4000,
"source": { "type": "workspace" }
},
{
"type": "input_tokens_per_minute",
"value": 500000,
"org_limit": 10000000,
"source": { "type": "workspace" }
}
]
},
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_016qriyigbdebqkzhMujdHkX",
"type": "workspace_rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Kd5wMv8nSq2LcXy6tRfJ4b",
"display_name": "Claude Opus 4.x"
},
"models": [
"claude-opus-4-5",
"claude-opus-4-5-20251101",
"claude-opus-4-6",
"claude-opus-4-7",
"claude-opus-4-8"
],
"limits": [
{
"type": "requests_per_minute",
"value": 1000,
"org_limit": 4000,
"source": { "type": "workspace" }
},
{
"type": "input_tokens_per_minute",
"value": 500000,
"org_limit": 10000000,
"source": { "type": "workspace" }
}
]
}
],
"next_page": null
}Incluir valores heredados
Para leer los límites aplicables de un espacio de trabajo en una sola solicitud, agrega el parámetro de consulta opcional include_inherited. Su valor predeterminado es false; un valor que no sea booleano devuelve un error 400. Con include_inherited=true:
datatiene una entrada por cada grupo que se aplica al espacio de trabajo y tiene un valor a nivel de organización, incluso si el espacio de trabajo no anula nada de él. Un grupo de modelos se aplica cuando el espacio de trabajo puede acceder al menos a uno de sus modelos.- El
limits[]de cada entrada enumera cada tipo de limitador para el que la organización tiene un valor en ese grupo, además de cualquier tipo que el espacio de trabajo anule. Cada tipo aparece una vez, con la anulación del espacio de trabajo cuando hay una almacenada y con el valor de la organización en caso contrario, por lo que una entrada puede combinar ambos. - El
sourcede cada valor permite distinguirlos:{"type": "workspace"}es una anulación almacenada, y{"type": "organization"}es un valor heredado, dondevaluees igual aorg_limit.
client = anthropic.Anthropic()
rate_limits = client.organization.workspaces.rate_limits.list(
"wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
include_inherited=True,
)
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value} ({limit.source.type})"){
"data": [
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_01NwFawrTvAijwqn8AjKVBPS",
"type": "workspace_rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Hq7YkP3mZ9dTwRx4cVbN2s",
"display_name": "Claude Opus 5.5"
},
"models": ["claude-opus-5-5"],
"limits": [
{
"type": "requests_per_minute",
"value": 1000,
"org_limit": 4000,
"source": { "type": "workspace" }
},
{
"type": "input_tokens_per_minute",
"value": 500000,
"org_limit": 10000000,
"source": { "type": "workspace" }
},
{
"type": "output_tokens_per_minute",
"value": 800000,
"org_limit": 800000,
"source": { "type": "organization" }
}
]
},
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_016qriyigbdebqkzhMujdHkX",
"type": "workspace_rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Kd5wMv8nSq2LcXy6tRfJ4b",
"display_name": "Claude Opus 4.x"
},
"models": [
"claude-opus-4-5",
"claude-opus-4-5-20251101",
"claude-opus-4-6",
"claude-opus-4-7",
"claude-opus-4-8"
],
"limits": [
{
"type": "requests_per_minute",
"value": 1000,
"org_limit": 4000,
"source": { "type": "workspace" }
},
{
"type": "input_tokens_per_minute",
"value": 500000,
"org_limit": 10000000,
"source": { "type": "workspace" }
},
{
"type": "output_tokens_per_minute",
"value": 800000,
"org_limit": 800000,
"source": { "type": "organization" }
}
]
},
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_01EyY8kq14eviKJPgepbgBH4",
"type": "workspace_rate_limit",
"group": { "type": "batch", "id": "rlg_01Wn3pBz6kCg9vHtQ7mLxD5a" },
"models": null,
"limits": [
{
"type": "enqueued_batch_requests",
"value": 500000,
"org_limit": 500000,
"source": { "type": "organization" }
}
]
}
],
"next_page": null
}Establecer límites de velocidad del espacio de trabajo
Para establecer o borrar los límites de velocidad de un espacio de trabajo para un grupo de límites de velocidad, envía una solicitud POST a /v1/organizations/workspaces/{workspace_id}/rate_limits/{rate_limit_id}. Para rate_limit_id, pasa el id de la entrada del grupo del endpoint de la organización, o el rate_limit_id de la entrada del grupo del endpoint de lista del espacio de trabajo. Para encontrar el ID de un grupo que el espacio de trabajo aún no sobrescribe, llama al endpoint de lista del espacio de trabajo con include_inherited=true, que devuelve los grupos para los que puedes establecer límites. Estos ID difieren entre organizaciones, así que búscalos en cada organización que administres.
El cuerpo de la solicitud tiene un array limits con una o más entradas {type, value}, cada una para un tipo de limitador diferente:
- Un
valueque sea un entero, cero o mayor, establece la anulación del espacio de trabajo para ese tipo de limitador. - Un
valuedenullborra la anulación, de modo que el espacio de trabajo vuelve a heredar el valor de la organización. Borrar un tipo de limitador que no tiene anulación no cambia nada. - Los tipos de limitador que la solicitud no nombra conservan sus valores actuales.
Puedes establecer estos tipos de limitador: requests_per_minute, input_tokens_per_minute, output_tokens_per_minute, input_tokens_per_minute_cache_aware, tokens_per_minute, tokens_per_day, tool_uses_per_second y, donde los endpoints de lista los muestren para tu organización, los límites del modo rápido fast_itpmca (tokens de entrada por minuto, con reconocimiento de caché) y fast_otpm (tokens de salida por minuto). Cuáles de ellos acepta un grupo depende de su group.type:
model_group: todos los tipos exceptotool_uses_per_secondweb_search: solotool_uses_per_secondbatch: solorequests_per_minute
Puedes borrar cualquiera de los tipos de limitador mencionados anteriormente en cualquiera de estos grupos. Los endpoints de lista pueden devolver tipos de limitador que no puedes establecer, como enqueued_batch_requests; enviar uno devuelve un error 400.
La API almacena un valor superior al límite de la organización para el mismo tipo de limitador, pero aplica el menor de los dos. El org_limit de la respuesta muestra el valor de la organización.
Los cambios surten efecto en aproximadamente una hora. Hasta que un cambio surta efecto, las solicitudes del espacio de trabajo siguen limitadas por los valores anteriores.
La API verifica toda la solicitud antes de cambiar cualquier cosa, por lo que una entrada no válida hace que la solicitud falle con un error 400 y no cambia nada. Si una solicitud pasa la validación, la API aplica las entradas una a la vez. Si falla la aplicación de una, la solicitud devuelve un error y las entradas anteriores a ella permanecen aplicadas. Cada entrada establece o borra un valor absoluto, por lo que puedes enviar la misma solicitud de nuevo de forma segura. Un reenvío reemplaza cualquier cambio que otra persona haya hecho entretanto en los tipos de limitador que nombra.
Aumenta las solicitudes por minuto del espacio de trabajo para el grupo de Claude Opus 5.5 a 2,000 y borra su anulación de tokens de entrada por minuto:
client = anthropic.Anthropic()
entry = client.organization.workspaces.rate_limits.update(
"rlt_01NwFawrTvAijwqn8AjKVBPS",
workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
limits=[
{"type": "requests_per_minute", "value": 2000},
{"type": "input_tokens_per_minute", "value": None},
],
)
for limit in entry.limits:
print(f"{limit.type}: {limit.value}")La respuesta es la entrada del grupo, con la forma de una entrada en la lista data del endpoint de lista del espacio de trabajo. Su limits enumera las anulaciones del espacio de trabajo en ese grupo después del cambio: un tipo de limitador borrado no aparece, y limits está vacío cuando no queda ninguna anulación. La respuesta incluye los cambios de la solicitud incluso cuando una solicitud de lista realizada justo después aún no los muestra.
{
"workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
"rate_limit_id": "rlt_01NwFawrTvAijwqn8AjKVBPS",
"type": "workspace_rate_limit",
"group": {
"type": "model_group",
"id": "rlg_01Hq7YkP3mZ9dTwRx4cVbN2s",
"display_name": "Claude Opus 5.5"
},
"models": ["claude-opus-5-5"],
"limits": [
{
"type": "requests_per_minute",
"value": 2000,
"org_limit": 4000,
"source": { "type": "workspace" }
}
]
}El endpoint devuelve un error 400 para una solicitud no válida o un espacio de trabajo archivado. Devuelve un error 404 cuando no se encuentra el espacio de trabajo, o cuando rate_limit_id nombra un grupo que el espacio de trabajo no puede usar.
Filtrar por tipo de grupo
Ambos endpoints de lista aceptan un parámetro de consulta opcional group_type que restringe la respuesta a una sola categoría:
client = anthropic.Anthropic()
rate_limits = client.organization.rate_limits.list(group_type="batch")
# Obtiene automáticamente más páginas según sea necesario.
for entry in rate_limits:
models = f" ({', '.join(entry.models)})" if entry.models else ""
print(f"{entry.group.type}{models}")
for limit in entry.limits:
print(f" {limit.type}: {limit.value}")Los valores válidos son model_group, batch, token_count, files, skills y web_search. Los valores token_count, files y skills devuelven una lista data vacía, porque ninguno de los endpoints de lista devuelve los límites de la Token Counting API, la Files API ni la Skills API.
Paginación
Ambos endpoints de lista aceptan los parámetros de consulta opcionales limit y page y devuelven un campo next_page. limit va de 1 a 1,000. Si lo omites, la respuesta contiene todas las entradas restantes y next_page es null. Si limit recorta la lista, next_page contiene un cursor: pásalo como page, con los mismos filtros, para obtener las siguientes entradas. Itera sobre next_page para que tu cliente obtenga todas las entradas.
Preguntas frecuentes
¿Qué cadenas de modelo aparecen en la lista models?
Cada ID de modelo y alias que cuenta contra el grupo, incluidos los ID con fecha (como claude-sonnet-4-5-20250929) y los alias sin fecha (como claude-sonnet-4-5). Busca cualquier cadena de modelo que pases a la API de Messages y la encontrarás en exactamente una entrada model_group.
La lista cubre los modelos a los que tu organización tiene acceso, por lo que puede diferir entre organizaciones.
¿Qué significa que falte un grupo en la respuesta del espacio de trabajo?
De forma predeterminada, la respuesta del espacio de trabajo enumera solo las anulaciones, por lo que un grupo que falta no tiene anulación en el espacio de trabajo y hereda el límite a nivel de organización. Pasa include_inherited=true para ver los valores heredados en el endpoint de espacios de trabajo, o consulta el endpoint de la organización. Con include_inherited=true, un grupo falta solo cuando no se aplica al espacio de trabajo o la organización no tiene un límite establecido para él.
¿Puedes actualizar los límites de velocidad con esta API?
Para un espacio de trabajo: Sí. El endpoint Establecer límites de velocidad del espacio de trabajoVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. establece o borra las anulaciones de un espacio de trabajo para un grupo de límites de velocidad. Pasa el id de nivel superior de la entrada correspondiente en la respuesta del endpoint de la organización como rate_limit_id, no el id rlg_ dentro de su group. Se aplica el menor entre la anulación del espacio de trabajo y el límite a nivel de organización, y un cambio surte efecto en aproximadamente una hora. Para ver el cuerpo de la solicitud y un ejemplo, consulta Establecer límites de velocidad del espacio de trabajo. También puedes establecer límites de velocidad del espacio de trabajo en la página Límites de frecuencia en la Claude Console: selecciona el espacio de trabajo en el menú desplegable Espacio de trabajo y haz clic en Editar junto a un modelo.
Para una organización: No. Para solicitar límites más altos, consulta Solicitar límites más altos.
Ver también
¿Te resultó útil esta página?