> ## 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.

# PredictLeads

> Record the cost of PredictLeads lookups on their tool spans

Record what each [PredictLeads](https://predictleads.com) company lookup costs next to your LLM spend. Every lookup becomes a tool span with its domain, the company data, latency and dollar cost, and the cost counts toward the trace total.

> [!NOTE]
>
> traceroot does not auto-instrument PredictLeads and does not know your plan's price. You trace the lookup 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 httpx
> ```

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

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 lookup.

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

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

## Usage

PredictLeads charges a fixed price per request, set by your plan. To record it:

1. Wrap the lookup in a function traced as a tool span (`type="tool"`).
2. Check that the request succeeded; PredictLeads does not bill a rejected one.
3. Report your price per call with `update_current_span(cost=...)` (`updateCurrentSpan` in TypeScript) while that span is open.

> [tab] Python
>
> ```python theme={null}
> import os
>
> import httpx
> from traceroot import observe, update_current_span
>
> PRICE_PER_CALL = 0.04  # your plan's price per request
> HEADERS = {
>     "X-Api-Key": os.environ["PREDICTLEADS_API_KEY"],
>     "X-Api-Token": os.environ["PREDICTLEADS_API_TOKEN"],
> }
>
> @observe(name="company_lookup", type="tool")
> def company_lookup(domain: str):
>     response = httpx.get(f"https://predictleads.com/api/v3/companies/{domain}", headers=HEADERS)
>     if response.is_success:
>         update_current_span(cost=PRICE_PER_CALL)
>     return response.json()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const PRICE_PER_CALL = 0.04; // your plan's price per request
> const headers = {
>   'X-Api-Key': process.env.PREDICTLEADS_API_KEY!,
>   'X-Api-Token': process.env.PREDICTLEADS_API_TOKEN!,
> };
>
> async function companyLookup(domain: string) {
>   return observe({ name: 'company_lookup', type: 'tool' }, async (d: string) => {
>     const response = await fetch(`https://predictleads.com/api/v3/companies/${d}`, { headers });
>     if (response.ok) updateCurrentSpan({ cost: PRICE_PER_CALL });
>     return response.json();
>   }, domain);
> }
> ```

Call `company_lookup` 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.

## 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 a `company_lookup` 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 domain passed to `company_lookup` |
| Output | The company data returned |
| Cost | Your price per call, in USD |
| Latency | Request duration |

## Limitations

* PredictLeads bills a lookup that returns no data yet, so report the cost on every successful response.
* A retry is another call and gets its own cost.

## Next steps

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

> [card] [Fixed price per call](https://traceroot.ai/docs/tracing/cost-tracking.md#fixed-price-per-call)
>
> Report your price on each billed call


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