# The LevelFour API: Cost and Savings Data Over REST

> One REST API for your spend and savings, with scoped keys, one response envelope, and signed webhooks when a saving moves.

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

Updated: 2026-10-19

August 26, 2026. By Gabriel Nielsen.

Cost data does more work where your team already looks: an internal dashboard, a finance model, a CI job, a ticket queue. The LevelFour API serves the same spend and savings data as the dashboard, so you can take it into any of them.

## One base URL, one envelope

Endpoints sit under `https://api.levelfour.ai` and take your [API key](https://docs.levelfour.ai/authentication) as a bearer token in the `Authorization` header. Every response comes back in the same envelope, with `success`, then `data` or `error`, then a `timestamp`, so one parser handles all of them.

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

An [error](https://docs.levelfour.ai/error-handling) sets `success` to `false` and puts a `code` such as `NOT_FOUND`, a `message`, and `details` under `error`. A list puts its rows in `items` beside a [pagination](https://docs.levelfour.ai/pagination) object with `total_pages` and `has_next`, and pages count from `1`. Each key can make 600 requests a minute. Past that, the API answers `429` with `RATE_LIMIT_EXCEEDED`.

## What you can reach

- [Costs](https://docs.levelfour.ai/resources/costs): spend summaries, breakdowns, trends, usage, allocation, and forecasts across the providers you connected.
- [Recommendations](https://docs.levelfour.ai/resources/recommendations): the savings LevelFour found and the decisions on them. You can accept one, reject it with a reason, or request its execution.
- [Realized savings](https://docs.levelfour.ai/resources/savings): what each completed recommendation saved, from the audit of your bill.
- [Commitments](https://docs.levelfour.ai/resources/commitments) and anomalies: your Reserved Instances and Savings Plans, and the spend spikes LevelFour detected.
- [Cost alerts](https://docs.levelfour.ai/resources/cost-alerts): create, change, pause, and delete budget, spend change, and commitment alerts, and read what they said.
- [Tags](https://docs.levelfour.ai/api-reference/tags) and [cost views](https://docs.levelfour.ai/api-reference/cost-views): provider tags, the virtual tags LevelFour assigns from your rules, and saved views you can read back.

The [API reference](https://docs.levelfour.ai/api-reference) has every endpoint, with its parameters and response shapes.

## Keys with a scope

Each key carries a scope and an optional expiry of 30, 60, or 90 days, both set when you [create it](https://docs.levelfour.ai/account/api-keys) in the dashboard. A read key covers the reads, and a write call made with one gets `403 Forbidden`. A read-write key adds the endpoints that record a decision in LevelFour, such as accepting a recommendation or requesting its execution. Neither scope changes anything in your cloud account: requesting execution starts the rollout in LevelFour.

Use read keys for dashboards, reports, and CI checks, and keep read-write keys for the automation that records decisions. When that automation retries a `POST`, send an `Idempotency-Key` header with a version 4 UUID: the API keeps a successful response for 24 hours and returns it to a retry with the same key instead of running the write again.

## Webhooks when a saving moves

[Register an endpoint](https://docs.levelfour.ai/webhooks) and LevelFour posts an event when a recommendation changes state or a rollout moves:

| Event | When it fires |
| --- | --- |
| `recommendation.accepted` | Someone accepted a savings recommendation |
| `recommendation.rejected` | Someone rejected one |
| `recommendation.rejection_reason_added` | Someone added a reason to a rejection |
| `recommendation.terms_accepted` | Someone accepted the terms for applying a recommendation |
| `recommendation.implementation_method_set` | Someone chose how a recommendation is delivered |
| `execution.approval_requested` | A member sent a recommendation to an admin to release |
| `optimization.started`, `optimization.completed`, `optimization.failed` | A rollout moved forward, finished, or failed |

Each request carries an HMAC-SHA256 signature in the Standard Webhooks format, with `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers, so your endpoint can confirm LevelFour sent it before acting on it. By default, the SDK verifiers reject a timestamp more than five minutes off, and LevelFour retries a delivery that gets no `2xx`, so deduplicate on `webhook-id`. Webhooks come with the Scale and Enterprise plans.

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

## Get started

Create a key in the dashboard under Settings > API Keys, then read the [API reference](https://docs.levelfour.ai/api-reference) for every endpoint. From a shell, [`l4 api`](https://docs.levelfour.ai/cli/commands/api) sends an authenticated request to any of them.

[Start with LevelFour](https://levelfour.ai/sign-up) and bring your cost data into your own tools.

## Frequently asked questions

### Can the LevelFour API change resources in my cloud?

No key changes anything in your cloud account. A read-write key records decisions in LevelFour, such as accepting a recommendation or requesting its execution, and the rollout runs from there.

### How do I verify that a webhook came from LevelFour?

Check the HMAC-SHA256 signature on each request against your endpoint's signing secret, which starts with `whsec_`. The headers follow the Standard Webhooks format, so any Standard Webhooks library can run the check.

### Which key should a CI job use?

A read key. It covers the reads a report or a check needs, and it cannot record a decision.

## 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`