Python SDK

levelfour is the Python client for the LevelFour API, in a sync form and an async one. Everything here is about the client itself. What each method takes and returns lives on the reference page for its sub-client, listed below.

Installation

pip install levelfour

Client setup

Sync client

from levelfour import LevelFour

client = LevelFour(
    api_key="l4_live_...",
    base_url="https://api.levelfour.ai",
    timeout=30.0,
    max_retries=2,
)

With LEVELFOUR_API_KEY in the environment, the constructor takes nothing:

client = LevelFour()

Prefer the empty constructor and the environment variable. An api_key written as an argument reaches version control with the file, and it stays in the history after you delete the line. Authentication covers keeping a key out of your source.

LevelFour works as a context manager:

with LevelFour() as client:
    summary = client.recommendations.get_savings_by_provider()

Async client

import asyncio
from levelfour import AsyncLevelFour

async def main():
    async with AsyncLevelFour() as client:
        summary = await client.recommendations.get_savings_by_provider()

asyncio.run(main())

Constructor options

Parameter	Type	Default
`api_key`	`str \| None`	`LEVELFOUR_API_KEY` env var
`base_url`	`str`	`https://api.levelfour.ai`
`timeout`	`float`	`30.0`
`max_retries`	`int`	`2`
`http_client`	`httpx.Client \| None`	Built-in
`headers`	`dict[str, str] \| None`	`None`

One type changes with the client you built. http_client takes an httpx.Client on LevelFour and an httpx.AsyncClient on AsyncLevelFour.

Cloning a client

with_options returns a copy of the client with the options you name changed:

long_timeout_client = client.with_options(timeout=60.0)

What the client exposes

Every sub-client hangs off the client you just built. The reference pages carry each method with its parameters, its response shape and a worked example.

Attribute	Reference
`client.recommendations`	Recommendations
`client.recommendations.audit`	Savings
`client.costs`	Costs
`client.providers`	Providers
`client.api_keys`	API keys
`client.webhooks`	Webhooks
`client.auth`	Authentication

Pagination

Methods that return paginated results return a SyncPager, or an AsyncPager on the async client.

Pagination has the iteration forms, sync and async, alongside the response envelope and the page size limit.

Request options

Override the client's defaults for one call:

from levelfour.core.request_options import RequestOptions

opts: RequestOptions = {
    "timeout_in_seconds": 60,
    "max_retries": 5,
    "additional_headers": {"X-Request-Id": "abc123"},
}

summary = client.recommendations.get_savings_by_provider(request_options=opts)

Option	Type	Description
`timeout_in_seconds`	`int`	Override request timeout
`max_retries`	`int`	Override max retry attempts
`additional_headers`	`dict[str, Any]`	Extra headers for this request
`additional_query_parameters`	`dict[str, Any]`	Extra query parameters
`additional_body_parameters`	`dict[str, Any]`	Extra body parameters

Resources has every method with its parameters and response shape, in Python alongside TypeScript and Go
Error handling is the exception hierarchy, what each error carries, and which failures the client retries
Webhooks is the verifier, the signature headers, the event types and the payloads
Authentication covers LEVELFOUR_API_KEY, key scopes, rotation and revocation
Quickstart is install, key, first call
TypeScript SDK and Go SDK cover the same surface in the other two languages