> ## Documentation Index
> Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up traceroot in a repository, follow the setup prompt in https://traceroot.ai/docs/getting-started/coding-agents.md.

# Exa

> Record the cost of Exa searches on their tool spans

Record what each [Exa](https://exa.ai) 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.

> [!NOTE]
>
> traceroot does not auto-instrument Exa. You trace the search with `observe` and report its cost yourself, and traceroot stores the cost you report. See [Tool and API calls](https://traceroot.ai/docs/tracing/cost-tracking.md#tool-and-api-calls) for how reported costs add up.

## Install

> [tab] Python
>
> ```bash theme={null}
> pip install traceroot exa-py
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @traceroot-ai/traceroot exa-js
> ```

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.

> [tab] Python
>
> ```python theme={null}
> import traceroot
>
> traceroot.initialize()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { TraceRoot } from '@traceroot-ai/traceroot';
>
> TraceRoot.initialize();
> ```

## Usage

Exa returns the dollar cost of each request in `costDollars`. To record it:

1. Wrap the search in a function traced as a tool span (`type="tool"`).
2. Read `costDollars.total` from the response.
3. Report it with `update_current_span(cost=...)` (`updateCurrentSpan` in TypeScript) while that span is open.

> [tab] Python
>
> ```python theme={null}
> from exa_py import Exa
> from traceroot import observe, update_current_span
>
> exa = Exa()  # reads EXA_API_KEY
>
> @observe(name="exa_search", type="tool")
> def web_search(query: str):
>     response = exa.search(query, num_results=3)
>     if response.cost_dollars:
>         update_current_span(cost=response.cost_dollars.total)
>     return response
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import Exa from 'exa-js';
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const exa = new Exa(process.env.EXA_API_KEY);
>
> async function webSearch(query: string) {
>   return observe({ name: 'exa_search', type: 'tool' }, async (q: string) => {
>     const response = await exa.search(q, { numResults: 3 });
>     if (response.costDollars) updateCurrentSpan({ cost: response.costDollars.total });
>     return response;
>   }, query);
> }
> ```

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 an exa\_search tool span with a cost of 0.007000, its search query input and the search results output](https://mintcdn.com/tracerootai/3SDwRl5xRxfZvr-4/images/tool_cost_price_in_response_v1.png?fit=max\&auto=format\&n=3SDwRl5xRxfZvr-4\&q=85\&s=6863aef569ace737aaa4d86c9d313ff5)

The tool span carries the price the search API returned

## Verify

Run your code and confirm the trace arrives:

1. **In the traceroot UI**: Navigate to **Tracing > Traces** in [traceroot Cloud](https://app.traceroot.ai). You should see an `exa_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

| Attribute | Description |
| - | - |
| Input | The query passed to `web_search` |
| Output | The search response |
| Cost | The `costDollars.total` you report, in USD |
| Latency | Request duration |

## Limitations

* A response without `costDollars` records no cost on the span.

## Next steps

> [card] [Python SDK Reference](https://traceroot.ai/docs/tracing/python-sdk.md)
>
> Explore the full Python SDK reference and instrumentation options.

> [card] [Price in the response](https://traceroot.ai/docs/tracing/cost-tracking.md#price-in-the-response)
>
> Report the price a provider returns with each request


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.