API Reference

Initialization

dexcost::init()

pub fn init(config: Config) -> Result<(), DexcostError>

Initialize the global SDK. Must be called before start_task, flush, or any wrapper client construction. Safe to call multiple times — only the first call takes effect.

Returns Err(DexcostError::InvalidApiKey) if the key format is invalid. Returns Err(DexcostError::AlreadyInitialized) on a second call.

dexcost::flush()

pub async fn flush() -> Result<(), DexcostError>

Force an immediate push of all buffered events to the Control Layer. No-op when no API key is configured. Returns Err(DexcostError::NotInitialized) if init has not been called.

dexcost::close()

pub fn close()

Stop the background pusher and release resources. Call at application shutdown. Due to OnceLock, the SDK cannot be re-initialized after close().

dexcost::buffer()

pub fn buffer() -> Result<Arc<Mutex<EventBuffer>>, DexcostError>

Return the global EventBuffer for advanced usage or testing.

dexcost::pricing_engine()

pub fn pricing_engine() -> Result<Arc<Mutex<PricingEngine>>, DexcostError>

Return the global PricingEngine for advanced usage or testing.

dexcost::rate_registry()

pub fn rate_registry() -> Result<Arc<Mutex<RateRegistry>>, DexcostError>

Return the global RateRegistry for registering per-service rates.

dexcost::service_catalog()

pub fn service_catalog() -> Result<Option<Arc<Mutex<ServiceCatalog>>>, DexcostError>

Return the global ServiceCatalog, or None when Config::track_http is false.

dexcost::set_context()

pub async fn set_context(ctx: DexcostContext)

Store ambient attribution in a process-wide RwLock. Wrapper clients and auto-tasks read this context via get_dexcost_context. Overwrites any previously set context.

dexcost::get_dexcost_context()

pub async fn get_dexcost_context() -> Option<DexcostContext>

Return a clone of the current ambient context, or None if not set.

dexcost::clear_dexcost_context()

pub async fn clear_dexcost_context()

Remove the current ambient context.

dexcost::config::validate_api_key()

pub fn validate_api_key(key: &str) -> Result<(), DexcostError>

Validate API key format. Returns Ok(()) for a valid dx_live_* or dx_test_* key or an empty string. Returns Err(DexcostError::InvalidApiKey) otherwise.

Tasks

dexcost::start_task()

pub async fn start_task(task_type: &str, opts: TaskOptions) -> Result<TrackedTask, DexcostError>

Begin tracking a new task. Returns a TrackedTask for recording costs. The parent task (if any) is linked automatically from task-local context when inside a scope call.

Returns Err(DexcostError::NotInitialized) if init has not been called.

TrackedTask::end()

pub async fn end(&mut self, status: TaskStatus) -> Result<(), DexcostError>

Finalize the task with the given status, persist it to the buffer, and print to the dev console if dev mode is active. Returns Err(DexcostError::TaskAlreadyEnded) if called more than once.

TrackedTask::scope()

pub async fn scope<F, T>(&self, f: F) -> T
where F: Future<Output = T>

Run future f with this task established in task-local storage. Any start_task call inside f automatically discovers this task as its parent and sets parent_task_id.

TrackedTask::link_trace()

pub fn link_trace(&mut self, provider: &str, trace_id: &str)

Attach an external observability trace to the task. Stored in task.metadata["_trace_links"] as a JSON array of {"provider": ..., "trace_id": ...} objects. Multiple calls accumulate entries.

TrackedTask::get_trace_links()

pub fn get_trace_links(&self) -> Vec<serde_json::Value>

Return all linked traces as a Vec of JSON objects with "provider" and "trace_id" keys. Returns an empty vec when no traces have been linked.

TrackedTask::task()

pub fn task(&self) -> &Task

Return a reference to the underlying Task struct.

TrackedTask::events()

pub fn events(&self) -> &[CostEvent]

Return the cost events recorded on this task so far.

dexcost::with_task()

pub async fn with_task<F, T>(task: Task, f: F) -> T
where F: Future<Output = T>

Run f with task set in task-local storage. The functional equivalent of TrackedTask::scope, accepting a bare Task struct.

dexcost::get_current_task()

pub fn get_current_task() -> Option<Task>

Return a clone of the task currently in task-local storage, or None.

Recording costs

TrackedTask::record_cost()

pub async fn record_cost(
    &mut self,
    service: &str,
    cost_usd: Decimal,
    details: Option<HashMap<String, serde_json::Value>>,
    event_type: Option<EventType>,
) -> Result<CostEvent, DexcostError>

Record a non-LLM cost event. Defaults to CostConfidence::Exact, PricingSource::Manual, and EventType::ExternalCost. Returns Err(DexcostError::TaskAlreadyEnded) if the task has ended.

TrackedTask::record_cost_with()

pub async fn record_cost_with(
    &mut self,
    service: &str,
    cost_usd: Decimal,
    event_type: Option<EventType>,
    opts: RecordCostOptions,
) -> Result<CostEvent, DexcostError>

Record a non-LLM cost event with optional overrides for CostConfidence, PricingSource, and pricing_version.

TrackedTask::record_usage()

pub async fn record_usage(
    &mut self,
    service: &str,
    units: i64,
) -> Result<CostEvent, DexcostError>

Look up service in the RateRegistry, multiply by units, and record an external_cost event with CostConfidence::Computed and PricingSource::RateRegistry. Returns an error when no rate is registered.

TrackedTask::record_llm_call()

pub async fn record_llm_call(
    &mut self,
    provider: &str,
    model: &str,
    input_tokens: i64,
    output_tokens: i64,
    cost_usd: Option<Decimal>,
    cached_tokens: Option<i64>,
    latency_ms: Option<i64>,
) -> Result<CostEvent, DexcostError>

Record an llm_call event. When cost_usd is None or zero, cost is auto-computed by the pricing engine from the bundled LiteLLM data.

TrackedTask::record_llm_call_with()

pub async fn record_llm_call_with(
    &mut self,
    provider: &str,
    model: &str,
    input_tokens: i64,
    output_tokens: i64,
    cost_usd: Option<Decimal>,
    cached_tokens: Option<i64>,
    latency_ms: Option<i64>,
    opts: RecordLlmCallOptions,
) -> Result<CostEvent, DexcostError>

Record an llm_call event with additional error_type, extra details, and cost confidence / source overrides.

TrackedTask::mark_retry()

pub async fn mark_retry(
    &mut self,
    reason: &str,
    cost_usd: Decimal,
) -> Result<CostEvent, DexcostError>

Create a retry_marker event that increments the task's retry_count and retry_cost_usd.

TrackedTask::mark_not_retry()

pub async fn mark_not_retry(
    &mut self,
    event_id: Option<&str>,
) -> Result<Option<CostEvent>, DexcostError>

Clear the retry flag on a retry-marked event. Pass None to target the most recent retry event, or Some(event_id) to target a specific one. Returns Ok(None) if no matching retry event is found.

Instrumentation

TrackedOpenAI::new()

pub fn new(pricing: Arc<PricingEngine>) -> Self

Construct a TrackedOpenAI wrapper that records llm_call events with provider = "openai".

TrackedOpenAI::record_response()

pub fn record_response(
    &self,
    model: &str,
    input_tokens: u32,
    output_tokens: u32,
    cached_tokens: Option<u32>,
    latency_ms: Option<u64>,
) -> CostEvent

Record an OpenAI-compatible response as an llm_call event. Cost is auto-priced from the bundled pricing data.

TrackedOpenAI::record_response_buffered()

pub fn record_response_buffered(
    &self,
    model: &str,
    input_tokens: u32,
    output_tokens: u32,
    cached_tokens: Option<u32>,
    latency_ms: Option<u64>,
    buffer: &mut EventBuffer,
) -> CostEvent

Record the response and write both the event and an auto-task to the supplied EventBuffer.

TrackedAnthropic::new()

pub fn new(pricing: Arc<PricingEngine>) -> Self

Construct a TrackedAnthropic wrapper that records llm_call events with provider = "anthropic".

TrackedAnthropic::record_response()

pub fn record_response(
    &self,
    model: &str,
    input_tokens: u32,
    output_tokens: u32,
    cache_creation_tokens: Option<u32>,
    cache_read_tokens: Option<u32>,
    latency_ms: Option<u64>,
) -> CostEvent

Record an Anthropic-compatible response. cache_creation_tokens are charged at the prompt-cache write rate; cache_read_tokens are charged at the cache-read discount rate and stored as event.cached_tokens.

TrackedGemini::new()

pub fn new(pricing: Arc<PricingEngine>) -> Self

Construct a TrackedGemini wrapper that records llm_call events with provider = "google".

TrackedGemini::record_response()

pub fn record_response(
    &self,
    model: &str,
    prompt_token_count: u32,
    candidates_token_count: u32,
    cached_content_token_count: Option<u32>,
    latency_ms: Option<u64>,
) -> CostEvent

Record a Gemini-compatible response. Gemini field names are stored in event.details for provenance.

clients::wrappers::record_openai_response()

pub async fn record_openai_response(
    buffer: &mut EventBuffer,
    pricing: &PricingEngine,
    task_id: &str,
    response: &serde_json::Value,
) -> Result<CostEvent, Box<dyn std::error::Error + Send + Sync>>

Extract token usage from an OpenAI-style response map and record an llm_call event. Reads model, usage.prompt_tokens, usage.completion_tokens, and optionally usage.prompt_tokens_details.cached_tokens.

clients::wrappers::record_anthropic_response()

pub async fn record_anthropic_response(
    buffer: &mut EventBuffer,
    pricing: &PricingEngine,
    task_id: &str,
    response: &serde_json::Value,
) -> Result<CostEvent, Box<dyn std::error::Error + Send + Sync>>

Extract token usage from an Anthropic-style response map. Reads model, usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens, and usage.cache_creation_input_tokens.

clients::wrappers::record_gemini_response()

pub async fn record_gemini_response(
    buffer: &mut EventBuffer,
    pricing: &PricingEngine,
    task_id: &str,
    response: &serde_json::Value,
) -> Result<CostEvent, Box<dyn std::error::Error + Send + Sync>>

Extract token usage from a Gemini-style response map. Reads model, usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount, and optionally usageMetadata.cachedContentTokenCount.

clients::wrappers::record_litellm_response()

pub async fn record_litellm_response(
    buffer: &mut EventBuffer,
    pricing: &PricingEngine,
    task_id: &str,
    response: &serde_json::Value,
) -> Result<CostEvent, Box<dyn std::error::Error + Send + Sync>>

Parse a LiteLLM response (OpenAI shape with provider-prefixed model) and record an llm_call event with provider = "litellm".

clients::wrappers::record_mcp_response()

pub fn record_mcp_response(
    buffer: &mut EventBuffer,
    catalog: &ServiceCatalog,
    task_id: &str,
    server_url: &str,
    response_size_bytes: Option<u64>,
) -> CostEvent

Record an external_cost event for an MCP server call. Cost is resolved by matching server_url against the service catalog; falls back to CostConfidence::Unknown and zero cost when no match is found.

clients::wrappers::record_mcp_tool_call()

pub fn record_mcp_tool_call(
    buffer: &mut EventBuffer,
    catalog: &ServiceCatalog,
    rates: Option<&RateRegistry>,
    task_id: &str,
    tool_name: &str,
    server: Option<&str>,
    latency_ms: Option<i64>,
    is_error: bool,
) -> CostEvent

Record an external_cost event for an MCP tool call identified by tool name. Cost is resolved via four fallback steps:

1. Rate registry: explicit mcp:<tool_name> key.
2. Tool map → catalog key → rate registry.
3. Tool map → catalog key → service catalog fixed cost.
4. Fallback: cost_usd = 0, CostConfidence::Unknown.

adapters::http::register_domain_rate()

pub fn register_domain_rate(domain: &str, cost_usd: Decimal, per: &str)

Register a per-call cost for domain in the global domain rate registry. Takes precedence over service catalog entries when both match. Idempotent — overwrites any existing rate for the same domain.

adapters::http::get_domain_rates()

pub fn get_domain_rates() -> HashMap<String, DomainRate>

Return a snapshot of all currently registered domain rates.

adapters::http::clear_domain_rates()

pub fn clear_domain_rates()

Remove all entries from the global domain rate registry.

adapters::http::record_http_cost()

pub fn record_http_cost(url: &str, task_id: &str)

Check whether url's hostname is registered in the domain rate registry and, if so, append a CostEvent to the in-process event log. Synchronous and lock-safe.

middleware::axum::dexcost_middleware()

#[cfg(feature = "axum-middleware")]
pub async fn dexcost_middleware(
    request: Request,
    next: Next,
    buffer: Arc<Mutex<EventBuffer>>,
    pricing: Option<Arc<Mutex<PricingEngine>>>,
) -> Response

Axum middleware function. Creates a dexcost task per request, records latency as a trace link, and ends the task with TaskStatus::Success for responses below 500 or TaskStatus::Failed for 5xx responses. Use with axum::middleware::from_fn.

middleware::tower::DexcostLayer

#[cfg(feature = "tower-middleware")]
pub struct DexcostLayer { ... }

impl DexcostLayer {
    pub fn new(buffer: Arc<Mutex<EventBuffer>>, pricing: Option<Arc<Mutex<PricingEngine>>>) -> Self
}

Tower Layer that wraps an inner service with DexcostService. Implements Clone. Use with tower::ServiceBuilder::layer.

middleware::actix::DexcostMiddleware

#[cfg(feature = "actix-middleware")]
pub struct DexcostMiddleware { ... }

impl DexcostMiddleware {
    pub fn new(buffer: Arc<Mutex<EventBuffer>>, pricing: Option<Arc<Mutex<PricingEngine>>>) -> Self
}

Actix-web middleware factory. Implements the actix_service::Transform trait. Register with actix_web::App::wrap.

Pricing & rates

PricingEngine

Calculates LLM costs from model name and token counts. Loaded from the embedded cost_map.json at construction time.

PricingEngine::new()

pub fn new() -> Self

Load the embedded pricing data and return a new PricingEngine.

PricingEngine::get_cost()

pub async fn get_cost(
    &self,
    model: &str,
    input_tokens: i64,
    output_tokens: i64,
    cached_tokens: i64,
    cache_creation_tokens: i64,
) -> CostResult

Compute the cost for an LLM call. Model resolution: exact match → provider-prefix strip → longest-prefix walk dropping trailing - components. Returns CostResult with CostConfidence::Unknown when the model is not found.

PricingEngine::get_cost_sync()

pub fn get_cost_sync(
    &self,
    model: &str,
    input_tokens: i64,
    output_tokens: i64,
    cached_tokens: i64,
    cache_creation_tokens: i64,
) -> CostResult

Synchronous variant of get_cost using a blocking read lock.

PricingEngine::set_custom_pricing()

pub async fn set_custom_pricing(&self, model: &str, input_per_1k: Decimal, output_per_1k: Decimal)

Override bundled pricing for model with custom per-1k-token rates. Custom pricing takes precedence over bundled data.

PricingEngine::set_custom_pricing_sync()

pub fn set_custom_pricing_sync(&self, model: &str, input_per_1k: Decimal, output_per_1k: Decimal)

Synchronous variant of set_custom_pricing.

PricingEngine::pricing_version()

pub async fn pricing_version(&self) -> String
pub fn pricing_version_sync(&self) -> String

Return the 12-character SHA-256 hex prefix of the loaded pricing data. Changes when pricing data is refreshed.

PricingEngine::refresh_from_server()

pub async fn refresh_from_server(&self, endpoint: &str) -> Result<(), Box<dyn std::error::Error + Send + Sync>>

Fetch the latest pricing data from {endpoint}/v1/api/pricing-data/latest and atomically replace the model map. Existing data is unchanged on error.

PricingEngine::start_background_refresh() / stop_background_refresh()

pub fn start_background_refresh(&self, endpoint: String, interval: Duration)
pub fn stop_background_refresh(&self)

Start or stop a background task that calls refresh_from_server on every interval tick. Performs an initial refresh before the first tick. Errors from the server are silently swallowed.

RateRegistry

Stores per-service cost rates for non-LLM services.

RateRegistry::new()

pub fn new() -> Self

Return an empty RateRegistry.

RateRegistry::register()

pub fn register(&mut self, service: &str, per: &str, cost_usd: Decimal)

Add or overwrite the rate for service. Invalidates the cached pricing version.

RateRegistry::get()

pub fn get(&self, service: &str) -> Option<&RateEntry>

Return the &RateEntry for service, or None if not found.

RateRegistry::rates()

pub fn rates(&self) -> &HashMap<String, RateEntry>

Return a reference to all registered rates.

RateRegistry::load_from_file()

pub fn load_from_file(&mut self, path: &Path) -> Result<usize, String>

Load and merge rates from a YAML file. Canonical format: entries nested under a top-level rates: key with per and cost_usd sub-keys. A legacy flat JSON array of {service, per, cost_usd} objects is also accepted. Returns the number of rates loaded.

RateRegistry::save_to_file()

pub fn save_to_file(&self, path: &Path) -> Result<usize, String>

Write all registered rates to a YAML file under a top-level rates: key, sorted by service name. Creates parent directories as needed.

RateRegistry::pricing_version()

pub fn pricing_version(&mut self) -> String

Return a 12-character SHA-256 hex hash of all registered rates in sorted order. Cached between register calls.

RateRegistry::default_path()

pub fn default_path() -> PathBuf

Return the default on-disk path for the registry: ~/.dexcost/rates.yaml. Overridable via DEXCOST_RATES_PATH.

ServiceCatalog

Manages the bundled service pricing catalog.

ServiceCatalog::new()

pub fn new() -> Self

Load the embedded service_prices.json and return a new ServiceCatalog.

ServiceCatalog::lookup()

pub fn lookup(&self, raw_url: &str) -> Option<&ServiceEntry>

Return the &ServiceEntry whose domains match the hostname in raw_url, or None.

ServiceCatalog::extract_cost()

pub fn extract_cost(
    &self,
    entry: &ServiceEntry,
    headers: &HashMap<String, String>,
    body: Option<&serde_json::Value>,
) -> Option<CostExtractionResult>

Extract cost from a matched catalog entry, optionally using HTTP response headers and body. Returns None when no pricing rule applies.

ServiceCatalog::refresh_from_url()

pub async fn refresh_from_url(&self, url: &str) -> Result<(), DexcostError>

Download an updated catalog JSON from url and merge it into the existing entries.

Types

Config

pub struct Config {
    pub api_key: Option<String>,
    pub batch_size: usize,
    pub flush_interval_secs: u64,
    pub redact_fields: Vec<String>,
    pub hash_customer_id: bool,
    pub environment: Option<String>,
    pub auto_instrument: Vec<String>,
    pub track_http: bool,
    pub service_catalog_url: Option<String>,
    pub buffer_path: Option<PathBuf>,
}

Global SDK configuration. See Configuration for field descriptions and defaults.

Key methods on Config:

TrackedTask

Wraps a Task and provides all cost-recording methods.

Task

The struct persisted to SQLite for each tracked task.

CostEvent

The struct persisted for each individual cost event within a task.

CostResult

pub struct CostResult {
    pub cost_usd: Decimal,
    pub cost_confidence: CostConfidence,
    pub pricing_source: PricingSource,
    pub pricing_version: String,
}

Result of a PricingEngine::get_cost() call.

TaskOptions

pub struct TaskOptions {
    pub customer_id: Option<String>,
    pub project_id: Option<String>,
    pub experiment_id: Option<String>,
    pub variant: Option<String>,
    pub metadata: Option<HashMap<String, serde_json::Value>>,
    pub parent_task_id: Option<String>,
    pub heuristics: Option<HeuristicConfig>,
}

Options for start_task. All fields default to None. Implements Default.

HeuristicConfig

pub struct HeuristicConfig {
    pub window_seconds: f64,  // default: 30.0
    pub threshold: f64,       // default: 0.8
}

Configuration for automatic retry detection via RetryHeuristicEngine. Set in TaskOptions::heuristics to activate.

RecordCostOptions

pub struct RecordCostOptions {
    pub cost_confidence: Option<CostConfidence>,
    pub pricing_source: Option<PricingSource>,
    pub pricing_version: Option<String>,
    pub details: Option<HashMap<String, serde_json::Value>>,
}

Optional overrides for TrackedTask::record_cost_with. All fields default to None. Implements Default.

RecordLlmCallOptions

pub struct RecordLlmCallOptions {
    pub error_type: Option<String>,
    pub details: Option<HashMap<String, serde_json::Value>>,
    pub cost_confidence: Option<CostConfidence>,
    pub pricing_source: Option<PricingSource>,
}

Optional overrides for TrackedTask::record_llm_call_with. error_type is merged into details["error_type"]. Implements Default.

DexcostContext

pub struct DexcostContext {
    pub customer_id: Option<String>,
    pub project_id: Option<String>,
    pub metadata: Option<HashMap<String, serde_json::Value>>,
    pub agent: Option<String>,
}

Ambient attribution context stored process-wide via set_context. Implements Default and Clone.

RateEntry

pub struct RateEntry {
    pub service: String,
    pub per: String,
    pub cost_usd: Decimal,
}

A single rate entry in the RateRegistry.

TaskStatus

pub enum TaskStatus {
    Pending,
    Running,
    Success,
    Failed,
}

Serialized as snake_case ("pending", "running", "success", "failed").

EventType

pub enum EventType {
    LlmCall,
    ExternalCost,
    ComputeCost,
    RetryMarker,
}

Serialized as snake_case ("llm_call", "external_cost", "compute_cost", "retry_marker").

CostConfidence

pub enum CostConfidence {
    Exact,
    Computed,
    Estimated,
    Unknown,
}

PricingSource

pub enum PricingSource {
    Litellm,
    Tokencost,
    ProviderResponse,
    Manual,
    Custom,
    RateRegistry,
    ServiceCatalog,
    UserOverride,
    Unknown,
}

DexcostError

pub enum DexcostError {
    NotInitialized,
    AlreadyInitialized,
    InvalidApiKey(String),
    TaskAlreadyEnded,
    Config(String),
    // ... additional variants
}

Returned by SDK functions on failure. DexcostError implements std::error::Error.

ALL_SUPPORTED_INSTRUMENTS

pub const ALL_SUPPORTED_INSTRUMENTS: &[&str] = &["openai", "anthropic", "gemini"];

Instrument names for which dedicated wrapper clients ship with the SDK.

VERSION

pub const VERSION: &str = env!("CARGO_PKG_VERSION");

The SDK version string, sourced from Cargo.toml at compile time.