API de Limites de Gastos

A 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 analise ou atue sobre as solicitações dos membros por um limite maior.

Para relatórios de uso e custo por usuário e por intervalos 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 próximos 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 de cada membro e o gasto acumulado no período:

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



Conceitos principais



A hierarquia de limites de gastos

Um 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 grupo), 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 é limitado com base em seu próprio gasto, não em um orçamento de grupo compartilhado.

Ler GET /v1/organizations/spend_limits/effective retorna cada membro atual 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 retorna o membro 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 o 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 é zerado. Um limite de gastos é identificado por seu par (scope, period). Atualmente, monthly é o único período suportado; o gasto mensal é zerado às 00



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 (conforme retornado 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 unidade menor; pode incluir uma parte fracionária (por exemplo, "41280.125"). Pode ser lido como "0" se a leitura de gasto estiver temporariamente indisponível; trate-o como informativo, não transacional.



Ciclo de vida da solicitação de aumento

Uma 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).



Limite de taxa

Todos os oito endpoints compartilham um único limite 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, 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 de 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"

{
  "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_..."
}



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 de 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"



Definir uma substituição por usuário

POST /v1/organizations/spend_limits define uma substituição de limite de gastos por usuário. Isso é um upsert com chave em (scope, period): definir um limite para um usuário e período que já tem um o sobrescreve no lugar. Este endpoint aceita apenas scope.type: "user"; 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 de 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" \
  --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 volta 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 de 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"



Solicitações de aumento de limite de gastos



Listar solicitações de aumento

GET /v1/organizations/spend_limit_increase_requests lista 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 de parâmetros e esquemas de resposta, consulte Listar solicitações de aumento de limite de gastos na referência da API.

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

Cada solicitação pendente carrega um spend_summary atualizado 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 de 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"



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 de 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" \
  --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 de 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" \
  --data '{"suppress_notification": true}'



Exemplos de fluxos de trabalho

Esses fluxos de trabalho combinam a API de Limites de Gastos com os endpoints de custo das APIs de Analytics. Os endpoints de custo do 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 limite que atualmente se aplica a cada membro. Inicie uma varredura com o Analytics para descobrir quais membros examinar e, em seguida, leia seus limites atuais com /effective.

Os endpoints de Limites de Gastos exigem os escopos spend_limits e os endpoints de custo do 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 via 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 "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   Cada solicitação carrega o actor.user_id do solicitante e um spend_summary atualizado 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 limiar e encaminhe limites maiores para revisão manual.

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

   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" \
     --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 ao limite de gastos

Encontre membros que estão se aproximando do limite 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"

   Cada linha carrega actor.user_id, actor.email e amount (o gasto do membro em centavos). Percorra as páginas via next_page para cobrir toda a organização.

2. Para os maiores gastadores (ou todos acima de um limiar em dólares), busque os limites efetivos em lotes:

   cURL

   

   curl "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"

   Cada linha retorna o limite como amount (null = ilimitado, "0" = apenas uso incluído) junto com period_to_date_spend.

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

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



Encontrar membros com uso em rápida mudança

Identifique membros cujo gasto aumentou de uma semana para outra.

1. Obtenha o custo diário por membro para as duas últimas 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"

   Com bucket_width definido, cada membro abrange uma linha por dia com uso; percorra as páginas via 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 membros cuja semana recente excede a semana anterior pelo múltiplo escolhido (por exemplo, três). O custo de dias recentes é provisório e pode ser revisado para cima; para comparações reproduzíveis, defina ending_at em ou antes de um data_refreshed_at retornado anteriormente (consulte Disponibilidade e atualização de dados).

3. Atue sobre os membros sinalizados: ajuste o limite com POST /v1/organizations/spend_limits ou entre em contato.



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 intocada. 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 volta ao que herdaria da hierarquia: seu padrão de grupo, nível de assento ou organização. Se nenhum padrão existir 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. Padrões de nível de assento, grupo e organização são configurados nas configurações de Organização do claude.ai.



Por que period_to_date_spend às vezes é lido como "0" para um membro ativo?

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



Veja também