SDKs

CostLens publishes official client libraries for the public API so you don't have to hand-roll request signing, pagination, or error handling. Both SDKs mirror the same one-resource-per-domain shape and are kept in sync with each other.

JavaScript / TypeScript#

npm install @aezona/costlens-sdk

Works in Node.js 18+, browsers, Deno, Cloudflare Workers, and Bun — anywhere with a global fetch. Zero runtime dependencies.

import { CostLensClient } from "@aezona/costlens-sdk";
 
const costlens = new CostLensClient({ apiKey: process.env.COSTLENS_API_KEY! });
 
const meta = await costlens.meta();
console.log(meta.scopes);
 
const { items, total } = await costlens.recommendations.list({ severity: "critical" });
console.log(`${total} critical recommendations`);
 
await costlens.recommendations.approve(items[0].id);

Errors are typed, so you catch once per call site instead of checking a status field on every response:

import { CostLensRateLimitError, CostLensAuthError } from "@aezona/costlens-sdk";
 
try {
  await costlens.recommendations.approve(id);
} catch (err) {
  if (err instanceof CostLensRateLimitError) {
    console.log(`Retry in ${err.retryAfterSeconds}s`);
  } else if (err instanceof CostLensAuthError) {
    console.log("Key is invalid, revoked, or missing a scope");
  } else {
    throw err;
  }
}

client.lastRateLimit reflects the X-RateLimit-* headers from the most recent call, with no separate network round-trip.

Python#

pip install aezona-costlens-sdk

Built on httpx — the only runtime dependency. Requires Python 3.9+.

from costlens_sdk import CostLensClient
 
with CostLensClient(api_key="cl_live_...") as costlens:
    meta = costlens.meta()
    print(meta["scopes"])
 
    page = costlens.recommendations.list(severity="critical")
    print(f"{page['total']} critical recommendations")
 
    if page["items"]:
        costlens.recommendations.approve(page["items"][0]["id"])

from costlens_sdk import CostLensRateLimitError, CostLensAuthError
 
try:
    costlens.recommendations.approve(rec_id)
except CostLensRateLimitError as e:
    print(f"Retry in {e.retry_after_seconds}s")
except CostLensAuthError:
    print("Key is invalid, revoked, or missing a scope")

CostLensClient is a context manager so its pooled connection closes deterministically — use with, or call .close() yourself in a long-lived process.

What's deliberately the same across both#

• Resources: recommendations, anomalies, insights, forecast, inventory, savings, autofix — one per /public/v1 domain, matching a key's scopes 1:1.
• insights.get()/insights.refresh(): get() is served from the last snapshot and never spends your AI budget; refresh() forces regeneration and is a real, billable call.
• autofix: no method to create or directly apply a fix — only to manage the approval queue CostLens's own rule engine already populates.
• Error hierarchy: a base API error plus dedicated subclasses for auth failures, not-found, rate limits, and the AI-budget limit.

Other languages#

No official SDK yet for your language? The interactive API reference documents every request/response shape, and the same bearer-token auth works from any HTTP client.