SDK Reference · Overview

SDK Reference

One client, two languages. The Bear Lumen SDK tracks AI cost with one call: hand it a raw provider response and it auto-detects the provider, extracts token usage, and reports the cost. Choose your language in the sidebar and every example follows along.

Installation & setup

Install the Node.js SDK:

npm install @bearlumen/node-sdk

Initialize once at startup. init() reads the BEARLUMEN_API_KEY environment variable, so there is no key to plumb through your code; constructing a client with an explicit key still works when you need several clients or custom config.

import { BearLumen, getBearLumen } from '@bearlumen/node-sdk';

// One-line setup: init() reads BEARLUMEN_API_KEY from the environment and
// registers a default client that getBearLumen() returns anywhere in your app.
BearLumen.init();
const bear = getBearLumen();

// Explicit constructor (fully supported), e.g. for multiple clients or a
// custom key source:
// const bear = new BearLumen({
//   apiKey: process.env.BEARLUMEN_API_KEY!,
//   baseUrl: 'https://api.bearlumen.com/v1',  // optional: override the API base URL (keep the /v1 prefix)
//   timeout: 30000,                           // optional: ms (default 30000)
// });

Confirm connectivity with a quick ping:

const { ok, organization_id } = await bear.ping();
console.log(ok, organization_id);
// -> true 'org_9f2c1a7b'  (connectivity + API key are valid)

Prefer to try it before installing? The SDK Playground runs these same calls from your browser as step-by-step notebooks, with simulated providers and a live per-key cost panel.

Explore the SDK

The reference is split by task. Your language choice carries across every page.

Tracking usage

track() a provider response, a stream, or a non-token service, or wrap() your client to track every call automatically.

Tracing agentic work

Spans that reconstruct the agent call tree, count outcomes, cap budgets, and survive queues.

Reading your costs

Query usage, break cost down by model, provider, feature, end user, or any custom dimension, and read margins.

Error handling

The per-language exception model, a status-to-exception reference, and retry patterns.

Requirements

Node.js >= 18.0.0
Package @bearlumen/node-sdk (written in TypeScript, full type definitions included)