---
title: "Record every run with one decorator — Retrace"
description: "Record AI agent executions with one decorator. Retrace captures every model call, tool call, cost, and error as an interactive, replayable timeline."
canonical: "https://retraceai.tech/features/record"
last-updated: 2026-08-26
format: text/markdown
---

# Record every run with one decorator

Wrap your agent once and Retrace captures the entire execution (every model call, tool call, decision, and error) as a structured timeline you can scrub, search, replay, and share.

## What it does

- **One decorator** — Add @retrace.record in Python or wrap a function with trace() in TypeScript. Your agent code stays exactly the same, there's no manual span plumbing to write.
- **Automatic capture** — Calls to the major model providers are instrumented for you: prompts, responses, token usage, latency, and cost all land on the timeline with no extra code.
- **Spans & timeline** — Every model call, tool call, and error becomes a typed span on an interactive timeline you can play back, pause, and scrub step by step.
- **Resilient by design** — An offline buffer queues events and flushes them on reconnect, with automatic transport fallback. Typed errors surface problems without ever crashing your agent.
- **Privacy built in** — Sensitive values like emails, phone numbers, keys, and tokens are redacted before anything is stored, on every plan.
- **Sampling & replay-ready** — A sample rate keeps high-volume agents affordable while keeping full fidelity on the runs you record. Mark a run resumable to unlock fork & replay later.

## Examples

Python, one decorator records the whole run.

```agent.py
import retrace

retrace.configure(api_key="rt_...")

@retrace.record(name="support-agent", resumable=True)
def run_agent(prompt: str) -> str:
    return agent.invoke(prompt)

run_agent("Where is my order?")
```

TypeScript, wrap any async function with trace().

```agent.ts
import { configure, trace } from "retrace-sdk";

configure({ apiKey: "rt_..." });

const runAgent = trace(
  async (prompt: string) => agent.invoke(prompt),
  { name: "support-agent", resumable: true },
);
```


## REST API

- `POST /api/v1/traces: ingest a trace`
- `GET /api/v1/traces/:id: fetch a run and its spans`
- `GET /api/v1/traces: list and filter runs`

## Related

- HTML page: https://retraceai.tech/features/record
- Documentation: https://docs.retraceai.tech
- OpenAPI specification: https://retraceai.tech/openapi.json
- Authentication for agents: https://retraceai.tech/auth.md