Configuration

SDK API

Function	Description
`initialize(config)`	Patches your LLM clients and starts exporting spans. Call once at process start; in Next.js that is `instrumentation.ts`.
`withSession(info, fn)`	Runs `fn` inside a session so every span it produces is linked under the session. `info` is a session id string, or `{ sessionId, userId?, metadata? }`. Required for tasks and task groups.
`task(name, fn)`	Optional boundary hint. Wraps a unit of work in a named span so Belvedir knows where one task starts and ends.
`flush()`	Forces pending spans to export. Await it before a serverless route returns (see below).
`reportOutcome(sessionId, outcome)`	Tells Belvedir whether the session actually worked (`"success"` or `"fail"`) from a signal only your app has. A `"fail"` keeps that session out of training data. Call it after `flush()`, or later from a webhook or job. It never throws; it returns `false` (with a logged warning) if Belvedir hasn’t ingested the session yet, so flush first and retry. Python: `report_outcome(session_id, outcome)`. Semantics and the HTTP form are on Outcomes.

Options

Python takes the same options, snake_cased (api_key, base_url, app_name, disable_batch, and instrument_http, the Python name for instrumentFetch, covering raw requests/httpx); instrumentModules is Node-only.

Option	Description
`apiKey`	Required. Your Belvedir API key.
`baseUrl`	Belvedir platform URL. Defaults to `https://platform.belvedir.ai`. Set it only when your traces should go to a different platform host.
`appName`	Your application name. Used to label traces. Defaults to `belvedir-loop-app`.
`disableBatch`	Send spans immediately instead of batching. Useful for testing.
`instrumentModules`	Your imported LLM SDKs, e.g. `{ openAI: openai.OpenAI, anthropic }`. Required in Next.js and other bundled or ESM environments. See Installation.
`instrumentFetch`	Node (Python: `instrument_http`). Capture LLM calls made with raw `fetch` to OpenAI-compatible endpoints (`POST .../chat/completions`), streamed responses included. Defaults to `true`; set `false` to opt out. Very long content is truncated on the span (completions at 200,000 characters, each prompt message at 100,000).

Environment variables

The SDK reads only what you pass to initialize(). Most apps wire these two variables to the SDK options:

Variable	Maps to	Notes
`BELVEDIR_API_KEY`	`apiKey`	Required. Starts with `bv_live_`.
`BELVEDIR_BASE_URL`	`baseUrl`	Optional. Defaults to `https://platform.belvedir.ai`.

Set them in .env.local (Next.js), a .env file, or your shell:

macOS / Linux
Windows (PowerShell)
Windows (cmd)

export BELVEDIR_API_KEY=bv_live_...

Add the line to ~/.zshrc or ~/.bashrc to persist it across terminal sessions.

$env:BELVEDIR_API_KEY = "bv_live_..."

That sets it for the current terminal only. To persist it, run setx BELVEDIR_API_KEY "bv_live_..." and open a new terminal.

set BELVEDIR_API_KEY=bv_live_...

On Vercel and other hosts, add BELVEDIR_API_KEY under the project’s environment variables and redeploy. Inside a benchmark run the variables are preset; pass them to initialize() like any other.

Flush on serverless

Spans export in batches on a background thread. A serverless function, script, or queue job can exit before the batch ships, so spans appear locally but never in production. Call flush() before the process or handler returns: in Node, await flush() (the promise is abandoned with the batch if you don’t await it); in Python, flush() is synchronous and returns once the export has completed. flush() never throws, and it silently no-ops in a process where initialize() never ran, so a missing flush and a missing initialize() look the same: no spans, no error. For local testing, disableBatch: true exports each span immediately instead.

Get started

Node SDK

Guides

Inference

Training

Benchmarks

Resources

SDK API

Options

Environment variables

Flush on serverless

​SDK API

​Options

​Environment variables

​Flush on serverless

SDK API

Options

Environment variables

Flush on serverless