Quickstart

This example creates a Captar runtime, starts a session with budget and policy, wraps an OpenAI client, tracks a tool call, and closes the session cleanly. Use it as the first end-to-end check that your integration is wired correctly. If this works, the rest of the docs should feel familiar rather than abstract.

import OpenAI from "openai";
import { createCaptar } from "@captar/sdk";

const captar = createCaptar({
  project: "support-bot",
  exporter: { url: process.env.CAPTAR_INGEST_URL! },
});

const session = await captar.startSession({
  budget: {
    maxSpendUsd: 2,
    finalizationReserveUsd: 0.2,
  },
  metadata: {
    _user: "u_123",
    _team: "support",
    feature: "chat",
  },
  policy: {
    call: {
      allowedModels: ["gpt-4.1-mini"],
      maxEstimatedCostUsd: 0.6,
    },
    tool: {
      requireApprovalFor: ["zendesk.createComment"],
    },
  },
});

const openai = captar.wrapOpenAI(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  { session },
);

const response = await openai.responses.create({
  model: "gpt-4.1-mini",
  input: "Help me answer this support ticket.",
  max_output_tokens: 200,
});

await captar.trackTool("zendesk.createComment", {
  session,
  estimate: 0.02,
}).run(async () => {
  return { ok: true };
});

await session.close();
await captar.flush();

What this shows

Captar estimates request cost before the provider call runs.

Budget is reserved locally so the session cannot overspend silently.

Model and tool policy are evaluated before execution proceeds.

Provider usage is reconciled after the response returns.

Trace, spend, and guardrail events are emitted for platform export.

Things to notice

createCaptar() is the project root, not a global singleton.
startSession() is where request-scoped budget and policy live.
wrapOpenAI() keeps the provider client you already know.
trackTool() should wrap external actions that matter to the trace.
flush() matters for jobs, scripts, and short-lived serverless requests.

Common adjustments

Tab Title
Tab Title
Tab Title

const session = await captar.startSession({
  budget: {
    maxSpendUsd: 0.75,
    finalizationReserveUsd: 0.1,
  },
});

policy: {
  tool: {
    requireApprovalFor: ["billing.issueRefund"],
  },
}

const captar = createCaptar({
  project: "support-bot",
});

Introduction

Getting Started

Core Concepts

Platform

Reference

Quickstart

Quickstart

What this shows

Things to notice

Common adjustments

Next reads

​Quickstart

​What this shows

​Things to notice

​Common adjustments

​Next reads

Quickstart

What this shows

Things to notice

Common adjustments

Next reads