Skip to main content

Getting started

CostKey is an SDK that observes supported AI-provider calls in your existing application and records cost, usage, latency, stack, and context when the endpoint and transport are covered. Prompt/response and tool content is captured only when the project explicitly enables text capture, the SDK allows body capture, and the endpoint exposes a supported response shape. One CLI command gets you started; no provider-routing gateway is required.

Start CostKey​

CostKey runs on your own machines. One command starts it with Docker:

curl -fsSL https://costkey.dev/install.sh | sh

Open http://localhost:4100, sign up and create your workspace. See Self-hosting for settings, HTTPS and upgrades.

Connect your app​

pipx run costkey setup

The setup command signs in to your CostKey (http://localhost:4100 by default; pass --host for another address), creates a project, writes COSTKEY_DSN to .env, detects your framework, and writes .costkey/setup.md with the exact snippet and no-code preload option. New projects start in metadata-only mode. Enable text capture deliberately in the project settings; existing projects retain their configured mode.

Supported detections include Next.js, Vite, Express, Fastify, Hono, Koa, NestJS, Remix, Astro, SvelteKit, Node/TypeScript, FastAPI, Django, Flask, and plain Python. Bundled JavaScript apps get a sourcemap warning with a link to sourcemap setup.

Initialize manually​

Prefer the setup command above. If you need to wire CostKey manually, copy your DSN from Settings, Projects in your CostKey console and initialize before your first AI call.

import costkey

costkey.init(
    dsn="http://ck_your_key@localhost:4100/your_project_id",
    release="v1.0.0",  # Track cost per deploy
)

No-code preload​

For Node servers, setup writes .costkey/node-options.env:

NODE_OPTIONS=--import costkey/register npm start

For Python servers, setup writes .costkey/sitecustomize.py:

PYTHONPATH="$PWD/.costkey:$PYTHONPATH" uvicorn app:app

That's it​

Supported provider calls made through the instrumented transport are now observed automatically for metadata, usage, timing, and attribution. Coverage depends on the endpoint, transport, response shape, capture mode, and whether the process flushes its telemetry; see the developer recipes and capability matrix.

Using an agent framework such as the OpenAI Agents SDK, LangGraph, CrewAI or the Vercel AI SDK? Add its integration to see each step and tool call; see Agents and frameworks.

import costkey
from anthropic import Anthropic

costkey.init(dsn="http://ck_your_key@localhost:4100/your_project_id")

client = Anthropic()

# Metadata, usage, latency, and stack are observed when this endpoint is covered.
# Prompt/response content requires explicit text capture in project settings.
response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing in one paragraph"}],
)
print(response.content[0].text)

Open your CostKey console and you'll see:

  • Known cost per priced observed call; missing prices remain unknown
  • Token usage (input, output, cache, and reasoning tokens when reported)
  • Latency and streaming metrics (TTFT, tokens/sec) when the transport exposes them
  • Stack trace showing the captured source frame when available
  • Call site grouping so you can see which observed code paths cost the most
  • Captured content: inspect prompts/completions only for calls allowed by project text-capture, SDK body-capture, endpoint, permission, and retention settings
  • System prompts and tool calls: inspect these only when content capture is enabled and the provider response shape exposes them
  • Agent runs: group model calls, tool calls, retries, and errors when the application supplies an explicit trace/execution boundary
  • Cost per deploy: set release to see how costs change across deployments
  • Executive summary: a plain-English summary of your AI spend for stakeholders

Add context​

Tag calls with metadata to slice costs by feature, team, or user.

with costkey.with_context(task="summarize", team="search", user_id="u_123"):
    response = client.messages.create(
        model="claude-sonnet-4-5-20250514",
        max_tokens=1024,
        messages=[{"role": "user", "content": f"Summarize: {document}"}],
    )

Group calls into traces​

When a single user action triggers multiple AI calls, group them with start_trace.

with costkey.start_trace(name="POST /api/search"):
    intent = classify_intent(query)       # AI call 1
    results = search(query, intent)       # AI call 2
    summary = summarize(results)          # AI call 3
    # Supported calls appear as one trace in the dashboard

Shut down cleanly​

Before your process exits, flush any pending events.

costkey.shutdown()

Next steps​