dexcost Documentation

All dexcost.init() parameters, environment variables, development mode, attribution context, and the CLI.

Configuration options

Pass any of these to dexcost.init(). All parameters are keyword-only after api_key.

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None` — falls back to `DEXCOST_API_KEY`	API key for cloud push. Must start with `dx_live_` (production) or `dx_test_` (sandbox).
`auto_instrument`	`list[str] \| None`	`None` (all installed providers)	Which LLM SDKs to auto-patch. `None` patches every installed provider in `ALL_SUPPORTED_INSTRUMENTS`; pass a list to limit scope; pass `[]` to disable auto-instrumentation entirely.
`track_http`	`bool`	`True`	Patch `requests`, `httpx`, `aiohttp`, `botocore`, and `urllib3` to record non-LLM HTTP costs.
`environment`	`str \| None`	`None` — falls back to `DEXCOST_ENV`	Set to `"development"` to enable dev console mode (events printed to terminal, no cloud push).
`batch_size`	`int`	`100`	Maximum number of events per sync batch sent to the Control Layer.
`flush_interval`	`float`	`5.0`	Seconds between background sync pushes.
`redact_fields`	`list[str] \| None`	`None` (no redaction)	Field names to remove from `details` before storage (e.g. `["prompt", "completion"]`).
`hash_customer_id`	`bool`	`False`	SHA-256 hash `customer_id` before storing it, so raw identifiers never leave the process.
`storage`	`str \| None`	`None` (auto-detect)	Force `"local"` to disable cloud push regardless of API key.
`buffer_path`	`str \| None`	`None` (default SQLite path)	Path to the local SQLite buffer file. Useful when the default path is on a read-only filesystem.
`service_catalog_url`	`str \| None`	`None`	URL to fetch an updated service catalog JSON at startup, extending the 163-service bundled catalog.
`enable_retry_heuristics`	`bool`	`False`	Opt in to heuristic retry detection via the `RetryHeuristicEngine` (sliding window, confidence-scored).
`retry_heuristic_window`	`float \| None`	`None` (uses tracker default)	Sliding-window size in seconds for heuristic retry detection.
`retry_heuristic_threshold`	`float \| None`	`None` (uses tracker default)	Confidence threshold (0.0–1.0) above which an event is flagged as a retry.

dexcost.init() returns the DexcostConfig instance it created. You rarely need to hold onto it because the config is stored globally and consulted by all SDK internals.

Environment variables

Variable	Description
`DEXCOST_API_KEY`	API key. Read when `api_key` is not passed to `init()` and `storage` is not `"local"`.
`DEXCOST_ENDPOINT`	Override the Control Layer URL. Defaults to `https://api.dexcost.io`.
`DEXCOST_ENV`	Set to `development` to enable dev console mode without passing `environment` to `init()`.

Environment variables are read inside DexcostConfig.__post_init__, so they take effect when init() is called.

Development mode

Pass environment="development" (or set DEXCOST_ENV=development) to enable dev mode:

import dexcost

dexcost.init(environment="development")
dexcost.set_context(customer_id="local-test")

In dev mode:

Every llm_call and external_cost event is printed to the terminal as it is recorded.
Task completion is printed with aggregated cost totals.
No data is written to the cloud — the SyncWorker is not started.
An API key is not required.

Dev mode is controlled by DexcostConfig.is_dev, which returns True when environment == "development".

dexcost.set_context() stores attribution values in a ContextVar so every subsequent LLM call and dexcost.task() in the same async task or thread inherits them automatically. dexcost also patches ThreadPoolExecutor at init() time so child threads (used by OpenAI, LangChain, and similar libraries for parallel work) inherit the same context.

dexcost.set_context(
    customer_id="acme-corp",
    project_id="chatbot-v2",
    metadata={"tier": "enterprise", "region": "us-east-1"},
    agent="support_agent",
)

Parameter	Type	Description
`customer_id`	`str \| None`	Identifier for the customer being served.
`project_id`	`str \| None`	Identifier for the project or product.
`metadata`	`dict \| None`	Arbitrary key-value pairs attached to every event in this context.
`agent`	`str \| None`	Agent name — used as `task_type` for auto-created session tasks instead of the default `"agent_session"`.

get_context() returns the current DexcostContext, or None if set_context() has not been called. clear_context() removes the current context.

CLI

The dexcost CLI requires no API key and works offline against the local SQLite buffer.

`dexcost status`

Show the state of the local buffer:

dexcost status
dexcost status --db /path/to/buffer.db

Output includes: DB location, event count, task count, last task timestamp, pending/synced event counts, pricing data version, storage mode, key type (if set), and versions of detected LLM SDKs.

`dexcost rates`

Manage the per-service cost rate registry:

# List all registered rates
dexcost rates --list

# Import rates from a YAML file
dexcost rates --import rates.yaml

# Export current rates to a YAML file
dexcost rates --export rates.yaml

YAML format expected by --import:

rates:
  maps.googleapis.com:
    per: request
    cost_usd: "0.005"
  ocr-api.com:
    per: page
    cost_usd: "0.01"

`dexcost scan`

Static-analysis scan of your codebase to find cost points that are not yet tracked:

dexcost scan ./src
dexcost scan ./src --generate-stubs

scan walks the target directory, detects LLM calls (reported as auto-instrumented), and flags external API calls that likely incur cost but have no record_cost() call nearby (reported as needing manual recording). No API key or network connection is required.

--generate-stubs prints ready-to-paste record_cost() snippets for each untracked cost point found.

Configuration