API de Limites de Gastos

A Spend Limits API (API de Limites de Gastos) permite que você defina um limite de gastos para cada membro do Claude Enterprise, veja de onde o limite de gastos de cada membro é herdado e revise ou tome ações sobre as solicitações dos membros por um limite maior.

Para relatórios de uso e custo por usuário e agrupados por intervalo de tempo, consulte APIs de Analytics.

Visão geral

A API expõe oito endpoints em dois recursos:

Use os endpoints de limites de gastos para responder "qual limite de gastos se aplica a cada membro, de onde ele vem e quão perto eles estão dele?" e para definir uma substituição por usuário. Use os endpoints de solicitações de aumento de limite de gastos para processar a fila de solicitações enviadas pelos membros.

Pré-requisitos

• Sua organização deve estar em um plano Claude Enterprise.
• Os créditos de uso devem estar ativados para sua organização. Seu proprietário principal pode ativá-los nas configurações de faturamento do claude.ai.

Início rápido

Liste o limite de gastos mensal efetivo e o gasto acumulado no período de cada membro:

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"

Conceitos principais

A hierarquia de limites de gastos

Um effective spend limit (limite de gastos efetivo) se aplica ao gasto de cada membro, resolvido a partir de uma hierarquia de níveis de escopo. Quando um membro não tem uma substituição por usuário, ele herda o limite de gastos configurado para seu grupo (se sua organização usa limites baseados em grupos), seu nível de assento ou o padrão de toda a organização. Um limite de gastos de grupo é um padrão por membro: cada membro que o herda é controlado em relação ao seu próprio gasto, não a um orçamento compartilhado do grupo.

Ler GET /v1/organizations/spend_limits/effective retorna todos os membros atuais com seu limite de gastos efetivo resolvido, de onde esse limite foi resolvido (source) e seu gasto acumulado no período. Definir uma substituição por usuário com POST /v1/organizations/spend_limits fixa um membro em um limite de gastos específico, independentemente do que ele herdaria de outra forma. Excluir a substituição o retorna ao limite de gastos herdado (ou o deixa ilimitado se nenhum existir).

O campo source na linha de cada membro informa de qual nível seu limite de gastos foi resolvido: user (uma substituição por usuário), seat_tier, rbac_group ou organization. Trate os tipos de escopo como um conjunto aberto; ignore valores desconhecidos em vez de falhar.

Período

period é a janela recorrente durante a qual o limite de gastos é aplicado e o gasto é redefinido. Um limite de gastos é identificado pelo seu par (scope, period). Atualmente, monthly é o único período suportado; o gasto mensal é redefinido às 00:00 UTC no primeiro dia de cada mês do calendário. Trate period como um conjunto aberto.

Valores e moeda

Todos os valores monetários são strings em unidades menores da moeda de faturamento da organização (centavos, para USD). Por exemplo, "50000" representa 500,00 USD. Faça o parse como decimal e divida por 100 para exibir em dólares; evite ponto flutuante binário para valores grandes.

amount é anulável. Na linha efetiva de um membro, null significa ilimitado (sem limite de gastos) e "0" significa que o membro não pode usar o Claude além do uso incluído em seu plano. Em uma linha de limite de gastos configurada (como retornada por GET /v1/organizations/spend_limits/{id}), null significa apenas que nenhum limite de gastos numérico está definido; leia a linha efetiva do membro para distinguir ilimitado de apenas uso incluído.

period_to_date_spend é o gasto do membro acumulado desde o início do period atual, no mesmo formato de unidades menores; ele pode incluir uma parte fracionária (por exemplo, "41280.125"). Ele pode aparecer como "0" se a leitura de gastos estiver temporariamente indisponível; trate-o como informativo, não transacional.

Ciclo de vida da solicitação de aumento

Uma spend limit increase request (solicitação de aumento de limite de gastos) é criada quando um membro clica em Request more usage no claude.ai. As solicitações não são criadas por meio desta API. O status de uma solicitação é um dos seguintes:

Tanto approved quanto denied são terminais. Um membro tem no máximo uma solicitação pending por vez.

Aprovar com POST /v1/organizations/spend_limit_increase_requests/{id}/approve grava a mesma linha de limite de gastos por usuário que POST /v1/organizations/spend_limits grava. Definir um limite de gastos diretamente não faz a transição de uma solicitação pendente; use o endpoint de aprovação para resolver uma solicitação.

Por padrão, a Anthropic envia um e-mail ao membro quando sua solicitação é aprovada ou negada. Passe suppress_notification: true ao aprovar ou negar para suprimir esse e-mail (por exemplo, quando seu próprio sistema notifica o membro).

Versionamento

Envie o cabeçalho anthropic-version em todas as solicitações; consulte Versões da API para ver as versões disponíveis.

Limite de taxa

Todos os oito endpoints compartilham um único "rate limit" (limite de taxa) por organização de 60 requisições por minuto. Requisições acima do limite retornam 429 Too Many Requests.

Paginação

GET /v1/organizations/spend_limits/effective e GET /v1/organizations/spend_limit_increase_requests são paginados com um cursor opaco. A primeira requisição retorna até limit linhas mais um cursor next_page; passe esse cursor inalterado como o parâmetro page na próxima requisição e repita até que next_page seja null.

Não altere os parâmetros de consulta no meio da sequência. Os cursores estão vinculados aos filtros que os emitiram. Se você alterar user_ids[], period[], status[] ou actor_ids[] e passar um cursor antigo, você receberá um 400 com "cursor does not match current query parameters". Em vez disso, inicie uma nova sequência a partir da primeira página.

Serializando parâmetros de lista

Parâmetros de lista usam notação de colchetes: repita o nome do parâmetro com [] para cada valor.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq

Respostas de erro

As respostas de erro seguem o formato padrão documentado em Erros. Cite o request_id do corpo da resposta ao entrar em contato com o suporte.

Limites de gastos

Listar o limite de gastos efetivo de cada membro

GET /v1/organizations/spend_limits/effective retorna uma linha por membro atual, refletindo o limite de gastos efetivo de cada membro, seu source na hierarquia de escopo e seu period_to_date_spend. Requer o escopo read:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Listar limites de gastos efetivos na referência da 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_..."
}

Obter um único limite de gastos

GET /v1/organizations/spend_limits/{spend_limit_id} retorna um limite de gastos configurado por ID. Use-o para inspecionar a linha que um campo spend_limit_id referenciou. Requer o escopo read:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Recuperar um limite de gastos na referência da 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"

Definir uma substituição por usuário

POST /v1/organizations/spend_limits define uma substituição de limite de gastos por usuário. Este é um upsert com chave em (scope, period): definir um limite para um usuário e período que já possui um o sobrescreve no lugar. Este endpoint aceita apenas scope.type: "user"; os padrões de nível de assento, grupo e organização são configurados nas configurações do claude.ai. Requer o escopo write:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Criar um limite de gastos na referência da 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"
}

Remover uma substituição por usuário

DELETE /v1/organizations/spend_limits/{spend_limit_id} remove uma substituição por usuário, após o que o membro retorna a qualquer padrão herdado de nível de assento, grupo ou organização. Linhas de nível de assento, grupo e organização não podem ser excluídas por meio deste endpoint. Requer o escopo write:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Excluir um limite de gastos na referência da 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"

Solicitações de aumento de limite de gastos

Listar solicitações de aumento

GET /v1/organizations/spend_limit_increase_requests lista as solicitações, da mais recente para a mais antiga. Filtre por status[] (pending, approved, denied) e actor_ids[]. A lista exclui solicitações cujo solicitante não é mais membro da organização. Requer o escopo read:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Listar solicitações de aumento de limite de gastos na referência da 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 solicitação pendente carrega um spend_summary em tempo real mostrando o limite de gastos efetivo atual do solicitante e o gasto acumulado no período, o suficiente para decidir sem uma consulta separada.

Obter uma única solicitação de aumento

GET /v1/organizations/spend_limit_increase_requests/{id} retorna uma solicitação por ID. Requer o escopo read:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Recuperar uma solicitação de aumento de limite de gastos na referência da 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"

Aprovar uma solicitação de aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/approve aprova uma solicitação pendente: grava um limite de gastos por usuário no amount fornecido pelo administrador para o solicitante e faz a transição da solicitação para approved. A solicitação não carrega um valor solicitado; você fornece o novo limite de gastos na aprovação. Requer o escopo write:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Aprovar uma solicitação de aumento de limite de gastos na referência da 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}'

Negar uma solicitação de aumento

POST /v1/organizations/spend_limit_increase_requests/{id}/deny nega uma solicitação pendente. Idempotente em denied: negar uma solicitação já negada retorna 200 com o recurso existente. O endpoint rejeita uma tentativa de negar uma solicitação já aprovada para que a automação possa distinguir uma nova tentativa de uma decisão conflitante. Requer o escopo write:spend_limits.

Para detalhes completos dos parâmetros e esquemas de resposta, consulte Negar uma solicitação de aumento de limite de gastos na referência da 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}'

Exemplos de fluxos de trabalho

Alguns desses fluxos de trabalho combinam a Spend Limits API com os endpoints de custo das APIs de Analytics. Os endpoints de custo de Analytics são projetados para relatórios de gastos de toda a organização em um intervalo de datas. GET /spend_limits/effective retorna o teto que se aplica atualmente a cada membro. Inicie uma varredura com Analytics para descobrir quais membros analisar e, em seguida, leia seus tetos atuais com /effective.

Os endpoints de Spend Limits exigem os escopos spend_limits e os endpoints de custo de Analytics exigem read:analytics; consulte APIs de Analytics para saber como provisionar o acesso. Todos os valores monetários em ambos são strings decimais em unidades menores (centavos). Ambas as APIs paginam com um cursor opaco. Defina um limit explícito e percorra as páginas por next_page até que seja null para cobrir toda a organização.

Automatizar o fluxo de revisão de solicitações de aumento

Execute um job agendado que busca solicitações pendentes, aplica a política de aprovação da sua organização e resolve cada uma.

1. Liste as solicitações pendentes:

   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 solicitação carrega o actor.user_id do solicitante e um spend_summary em tempo real com seu amount efetivo atual e period_to_date_spend, o suficiente para decidir sem uma consulta separada.

2. Aplique sua política. Por exemplo, aprove automaticamente quando o amount atual do membro estiver abaixo de um limite e encaminhe tetos maiores para revisão manual.

3. Resolva cada solicitação. Para aprovar, forneça o novo teto:

   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 negar, faça POST para .../{id}/deny em vez disso. Passe suppress_notification: true quando seu próprio sistema notificar o solicitante.

Identificar membros próximos do seu limite de gastos

Encontre membros que estão se aproximando do seu teto para que você possa aumentá-lo antes que sejam bloqueados.

1. Obtenha o gasto acumulado no mês de cada membro a partir da API de Analytics (uma linha por membro, maior gasto primeiro por padrão):

   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 linha carrega actor.user_id, actor.email e amount (o gasto do membro em centavos). Percorra as páginas por next_page para cobrir toda a organização.

2. Para os maiores gastadores (ou todos acima de um limite em dólares), busque os tetos efetivos em 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 linha retorna o teto como amount (null = ilimitado, "0" = apenas uso incluído) junto com period_to_date_spend.

3. Para cada membro com um teto positivo, calcule period_to_date_spend / amount e sinalize aqueles que estão no seu limite ou acima dele (por exemplo, 80 por cento). Trate um teto "0" como já no limite. Não há filtro do lado do servidor para essa proporção.

4. Tome ações sobre os membros sinalizados: aumente o teto com POST /v1/organizations/spend_limits, aprove uma solicitação de aumento pendente se existir uma ou entre em contato com o membro.

Encontrar membros com uso mudando rapidamente

Identifique membros cujo gasto aumentou de uma semana para outra.

1. Obtenha o custo diário por membro das últimas duas semanas a partir da 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"

   Com bucket_width definido, cada membro abrange uma linha por dia com uso; percorra as páginas por next_page para coletar a série completa de cada membro.

2. Agrupe as linhas por actor.user_id. Para cada membro, some os sete dias mais recentes e os sete dias anteriores. Sinalize os membros cuja semana recente excede a semana anterior pelo múltiplo escolhido por você (por exemplo, três). O custo dos dias recentes é provisório e pode ser revisado para cima; para comparações repetíveis, defina ending_at em ou antes de um data_refreshed_at retornado anteriormente (consulte Disponibilidade e atualização dos dados).

3. Tome ações sobre os membros sinalizados: ajuste o teto com POST /v1/organizations/spend_limits ou entre em contato.

Aumentar temporariamente o limite de gastos de um membro durante um incidente

Dê a um respondente de incidentes espaço para trabalhar enquanto um incidente está aberto: aumente seu teto de gastos quando o incidente começar e reverta-o após o encerramento do incidente. Condicione o aumento ao seu sistema de gerenciamento de incidentes, por exemplo, exigindo um ID de incidente ativo com o membro atribuído a ele.

1. Leia o teto atual do membro e registre-o para a reversão:

   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. Aumente o teto:

   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. Se os respondentes precisarem de acesso mais amplo durante um incidente, pré-provisione um grupo de respondentes de incidentes cuja função personalizada o conceda e adicione o membro pela duração:

   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"}'

   Consulte Gerenciamento de usuários para os endpoints de grupo.

4. Quando seu sistema de incidentes marcar o incidente como encerrado, reverta ambas as alterações: restaure o limite de gastos que você registrou na etapa 1 (ou exclua a substituição com DELETE /v1/organizations/spend_limits/{spend_limit_id} se o membro não tinha nenhuma) e remova o membro do grupo com DELETE /v1/organizations/rbac_groups/{rbac_group_id}/members/{user_id}.

Perguntas frequentes

Definir um limite de gastos diretamente resolve a solicitação de aumento pendente de um membro?

Não. POST /v1/organizations/spend_limits grava a substituição, mas deixa a solicitação pendente intacta. Use POST /v1/organizations/spend_limit_increase_requests/{id}/approve para resolver a solicitação e gravar a substituição em uma única chamada.

O que acontece quando eu excluo uma substituição por usuário?

O membro retorna ao que herdaria da hierarquia: o padrão do seu grupo, nível de assento ou organização. Se não existir nenhum padrão em nenhum nível, o membro fica ilimitado.

Posso definir um padrão de nível de assento ou de toda a organização por meio desta API?

Não. Apenas substituições por usuário podem ser gravadas por meio desta API. Os padrões de nível de assento, grupo e organização são configurados nas configurações da Organização no claude.ai.

Por que period_to_date_spend às vezes aparece como "0" para um membro ativo?

A leitura de gastos pode estar temporariamente indisponível, caso em que o campo aparece como "0" em vez de gerar erro. Trate-o como informativo.

Veja também