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

# TinyFish

> Record the cost of TinyFish browser sessions on their tool spans

Record what each [TinyFish](https://tinyfish.ai) remote browser session costs next to your LLM spend. Every session becomes a tool span with its URL, result, duration and dollar cost, and the cost counts toward the trace total.

> [!NOTE]
>
> traceroot does not auto-instrument TinyFish and does not know your rate. You trace the session 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 session.

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

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

## Usage

TinyFish bills remote browsers by the minute and returns no price, so you estimate the cost from the session's length. To record it:

1. Wrap the session in a function traced as a tool span (`type="tool"`).
2. Time the session from creation to close.
3. Multiply the minutes by your price per minute and report it with `update_current_span(cost=...)` (`updateCurrentSpan` in TypeScript) before the span closes. A `finally` block reports it even when the session fails.

> [tab] Python
>
> ```python theme={null}
> import os
> import time
>
> import httpx
> from traceroot import observe, update_current_span
>
> PRICE_PER_MINUTE = 0.002  # your price per browser minute
> API = "https://api.browser.tinyfish.ai"
> HEADERS = {"X-API-Key": os.environ["TINYFISH_API_KEY"]}
>
> @observe(name="tinyfish_open_page", type="tool")
> def browse(url: str):
>     start = time.monotonic()
>     response = httpx.post(API, headers=HEADERS, json={"url": url}, timeout=60)
>     response.raise_for_status()
>     session = response.json()
>     try:
>         ...  # drive the browser through session["cdp_url"]
>     finally:
>         minutes = (time.monotonic() - start) / 60
>         update_current_span(cost=minutes * PRICE_PER_MINUTE)
>         httpx.delete(f"{API}/{session['session_id']}", headers=HEADERS)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { observe, updateCurrentSpan } from '@traceroot-ai/traceroot';
>
> const PRICE_PER_MINUTE = 0.002; // your price per browser minute
> const API = 'https://api.browser.tinyfish.ai';
> const headers = { 'X-API-Key': process.env.TINYFISH_API_KEY!, 'Content-Type': 'application/json' };
>
> async function browse(url: string) {
>   return observe({ name: 'tinyfish_open_page', type: 'tool' }, async (u: string) => {
>     const start = performance.now();
>     const created = await fetch(API, { method: 'POST', headers, body: JSON.stringify({ url: u }) });
>     if (!created.ok) throw new Error(`TinyFish session failed: ${created.status}`);
>     const session = await created.json();
>     try {
>       // drive the browser through session.cdp_url
>     } finally {
>       const minutes = (performance.now() - start) / 60000;
>       updateCurrentSpan({ cost: minutes * PRICE_PER_MINUTE });
>       await fetch(`${API}/${session.session_id}`, { method: 'DELETE', headers });
>     }
>   }, url);
> }
> ```

Call `browse` 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 tinyfish\_open\_page tool span with a cost of 0.000092, the page URL input and the loaded page title output](https://mintcdn.com/tracerootai/3SDwRl5xRxfZvr-4/images/tool_cost_time_used_v1.png?fit=max\&auto=format\&n=3SDwRl5xRxfZvr-4\&q=85\&s=1926ae586939d607f3710c4eabc5fa46)

Browser minutes at the per-minute 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](https://app.traceroot.ai). You should see a `tinyfish_open_page` 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 URL passed to `browse` |
| Output | What `browse` returns, such as the page title |
| Cost | Session minutes × your price per minute, in USD |
| Latency | Session duration |

## Limitations

* The cost is an estimate: TinyFish bills from its own usage records, which can run a little longer.

## Next steps

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

> [card] [Time used](https://traceroot.ai/docs/tracing/cost-tracking.md#time-used)
>
> Report time used at your price per minute


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