# A API da LevelFour: dados de custo e economia via REST

> Uma API REST para o seu gasto e a sua economia, com API keys de escopo definido, o mesmo envelope em toda resposta e webhooks assinados a cada passo de uma economia.

Source: https://levelfour.ai/blog/api-da-levelfour

Updated: 2026-10-19

26 de agosto de 2026. Por Gabriel Nielsen.

Dado de custo rende mais onde o seu time já olha: num dashboard interno, no modelo do financeiro, num job de CI, na fila de tickets. A API da LevelFour serve os mesmos dados de gasto e de economia que o dashboard mostra, para você levar esses números a qualquer um desses lugares.

## Uma URL base e um envelope só

Os endpoints ficam em `https://api.levelfour.ai` e recebem a sua [API key](https://docs.levelfour.ai/authentication) como bearer token no header `Authorization`. Toda resposta volta no mesmo envelope, com `success`, depois `data` ou `error` e, por último, um `timestamp`. Um parser só dá conta de todas.

```bash
curl -H "Authorization: Bearer $LEVELFOUR_API_KEY" \
  https://api.levelfour.ai/api/v1/recommendations/summary
```

Num [erro](https://docs.levelfour.ai/error-handling), o `success` vem como `false`, e o `error` traz um `code`, como `NOT_FOUND`, uma `message` e os `details`. Uma lista põe as linhas em `items`, ao lado de um objeto de [paginação](https://docs.levelfour.ai/pagination) com `total_pages` e `has_next`, e as páginas começam em `1`. Cada chave faz até 600 requisições por minuto. Acima disso, a API responde `429` com o código `RATE_LIMIT_EXCEEDED`.

## O que dá para acessar

- [Custos](https://docs.levelfour.ai/resources/costs): resumos de gasto, detalhamentos, tendências, uso, alocação e forecasts de todos os provedores que você conectou.
- [Recomendações](https://docs.levelfour.ai/resources/recommendations): as economias que a LevelFour encontrou e as decisões sobre elas. Você aceita uma recomendação, rejeita com um motivo ou pede a execução.
- [Economia realizada](https://docs.levelfour.ai/resources/savings): quanto cada recomendação concluída economizou, segundo a auditoria da sua fatura.
- [Commitments](https://docs.levelfour.ai/resources/commitments) e anomalias: as suas Reserved Instances e os seus Savings Plans, e os picos de gasto que a LevelFour detectou.
- [Alertas de custo](https://docs.levelfour.ai/resources/cost-alerts): crie, altere, pause e exclua alertas de budget, de variação de gasto e de commitments, e leia os avisos que eles mandaram.
- [Tags](https://docs.levelfour.ai/api-reference/tags) e [visões de custo](https://docs.levelfour.ai/api-reference/cost-views): as tags dos provedores, as virtual tags que a LevelFour atribui pelas suas regras e as visões que você salvou, para consultar depois.

A [referência da API](https://docs.levelfour.ai/api-reference) traz cada endpoint com os seus parâmetros e o formato da resposta.

## Chaves com escopo

Cada API key tem um escopo e, se você quiser, um prazo de validade de 30, 60 ou 90 dias, os dois escolhidos quando você [cria a chave](https://docs.levelfour.ai/account/api-keys) no dashboard. A de leitura cobre as leituras, e uma chamada de escrita feita com ela recebe `403 Forbidden`. A de leitura e escrita libera também os endpoints que registram uma decisão na LevelFour, como aceitar uma recomendação ou pedir a execução dela. Nenhum dos dois escopos muda nada na sua conta de cloud: pedir a execução inicia o rollout dentro da LevelFour.

Para dashboards, relatórios e checks de CI, use a chave de leitura, e guarde a de leitura e escrita para a automação que registra decisões. Quando essa automação repete um `POST`, mande o header `Idempotency-Key` com um UUID versão 4: a API guarda a resposta de sucesso por 24 horas e a devolve a uma nova tentativa com a mesma chave, sem rodar a escrita outra vez.

## Webhooks a cada passo de uma economia

[Cadastre um endpoint](https://docs.levelfour.ai/webhooks) e a LevelFour envia um evento quando uma recomendação muda de estado ou um rollout avança:

| Evento | Quando dispara |
| --- | --- |
| `recommendation.accepted` | Alguém aceitou uma recomendação de economia |
| `recommendation.rejected` | Alguém rejeitou uma recomendação |
| `recommendation.rejection_reason_added` | Alguém deu o motivo de uma rejeição |
| `recommendation.terms_accepted` | Alguém aceitou os termos para aplicar uma recomendação |
| `recommendation.implementation_method_set` | Alguém escolheu como uma recomendação vai ser entregue |
| `execution.approval_requested` | Um membro mandou uma recomendação para um administrador liberar |
| `optimization.started`, `optimization.completed`, `optimization.failed` | Um rollout avançou, terminou ou falhou |

Cada requisição leva uma assinatura HMAC-SHA256 no formato Standard Webhooks, com os headers `webhook-id`, `webhook-timestamp` e `webhook-signature`, para o seu endpoint confirmar que foi a LevelFour quem enviou antes de agir. Por padrão, os verificadores dos SDKs recusam um timestamp com mais de cinco minutos de diferença, e a LevelFour reenvia toda entrega que não recebe um `2xx`: use o `webhook-id` para descartar as repetidas. Os webhooks vêm nos planos Scale e Enterprise.

```bash
curl -X POST https://api.levelfour.ai/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer $LEVELFOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhooks/levelfour", "event_types": ["recommendation.accepted", "optimization.completed"]}'
```

## Como começar

Crie uma chave no dashboard, em Settings > API Keys, e veja todos os endpoints na [referência da API](https://docs.levelfour.ai/api-reference). Do shell, o [`l4 api`](https://docs.levelfour.ai/cli/commands/api) manda uma requisição autenticada para qualquer um deles.

[Comece com a LevelFour](https://levelfour.ai/sign-up) e leve os seus dados de custo para as suas ferramentas.

## Perguntas frequentes

### A API da LevelFour consegue mudar recursos na minha cloud?

Não. Nenhuma chave muda nada na sua conta de cloud. A chave de leitura e escrita registra decisões na LevelFour, como aceitar uma recomendação ou pedir a execução dela, e o rollout segue de lá.

### Como eu confirmo que um webhook veio da LevelFour?

Confira a assinatura HMAC-SHA256 de cada requisição com o secret de assinatura do seu endpoint, que começa com `whsec_`. Os headers seguem o formato Standard Webhooks, então qualquer biblioteca de Standard Webhooks faz essa verificação.

### Que chave um job de CI deve usar?

Uma chave de leitura. Ela cobre as leituras de que um relatório ou um check precisa, e não consegue registrar decisão nenhuma.

## See what LevelFour can save you

[Start free trial](https://levelfour.ai/sign-up) · [Get in touch](https://levelfour.cal.com/)

## About LevelFour

The FinOps platform that actually cuts costs. One system of record for Cloud, SaaS, and AI spend. LevelFour applies each saving, or your engineers merge it as code.

- **Cloud Savings**: 30% success fee on savings found and applied. No hidden charges, only pay on what you actually save.
- **Pro**: $30 per month · Up to $2,500 spend/mo
- **Scale**: $200 per month · Up to $7,500 spend/mo
- **Enterprise**: Custom · Unlimited spend

[Pricing](https://levelfour.ai/pricing.md) · [Guide for agents (llms.txt)](https://levelfour.ai/llms.txt) · [Documentation](https://docs.levelfour.ai) · MCP server: `https://mcp.levelfour.ai/mcp`