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 tome ações 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 distribuídos 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óximo o membro está 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 em relação ao seu próprio gasto, não a um orçamento compartilhado do grupo.

A leitura de 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 a 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 pelo 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 entre ilimitado e 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 aparecer 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 transiciona 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 sobrescreve-o 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 transiciona a 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}'



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 aparece como "0" para um membro ativo?

A leitura de gasto 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