Skip to main content
Record what each Tavily search costs next to your LLM spend. Every search becomes a tool span with its query, results, latency and dollar cost, and the cost counts toward the trace total.
traceroot does not auto-instrument Tavily and does not know your plan’s price. You trace the search with observe and report its cost yourself, and traceroot stores the cost you report. See Tool and API calls for how reported costs add up.

Install

Reporting a cost requires traceroot 0.5.0 or later, or @traceroot-ai/traceroot 0.7.0 or later.

Set up

Initialize traceroot once at startup. No integration flag is needed: the observe wrapper in the next step traces the search.

Usage

Tavily bills in credits, and a credit’s dollar price depends on your plan. It returns the credits a search used when you ask for usage. To record the cost:
  1. Wrap the search in a function traced as a tool span (type="tool").
  2. Ask for usage with include_usage=True (includeUsage: true in TypeScript) and read the credits used.
  3. Multiply by your price per credit and report it with update_current_span(cost=...) (updateCurrentSpan in TypeScript) while that span is open.
Call web_search from your agent like any other function. Its span nests under the span that called it, and its cost adds to that trace’s total.
Span details for a tavily_search tool span with a cost of 0.008000 and its search query input

One credit at the plan rate on the tool span

Verify

Run your code and confirm the trace arrives:
  1. In the traceroot UI: Navigate to Tracing > Traces in traceroot Cloud. You should see a tavily_search span, at the root or under your agent’s span. Open it to see its cost; the trace’s total cost includes it.
  2. Via the CLI: Run traceroot traces list to inspect your recent traces from the terminal.

What gets captured

Limitations

  • Tavily returns credits only when the search asks for usage; without it the span records no cost.
  • Set PRICE_PER_CREDIT to your own plan’s rate.

Next steps

Python SDK Reference

Explore the full Python SDK reference and instrumentation options.

Credits or quota

Report credits used at your plan’s price per credit