# Traces and model prices

> Track your AI agent runs in ClickClacks: send $agent_run and $agent_step events, read runs, steps, outcomes, durations and cost, set model prices, and join runs to the people behind them.

- Canonical URL: https://clickclacks.io/docs/guides/traces
- Section: Product guides
- Last updated: 2026-09-26

If your product runs AI agents, Traces shows every run: what it did step by step, whether it finished, how long it took, what it cost, and what the person did around it.

## What a trace is {#what}

A **run** is one job your agent did, end to end, such as “summarize this ticket”. It is made of **steps**: each model call and each tool call. ClickClacks stores token counts, not prompts. An output preview is optional, and you decide per step whether to send one.

## Send your runs {#send}

Runs arrive as two special events, sent from your server with the [server API](https://clickclacks.io/docs/api.md) and a server source’s key:

- one `$agent_step` for each completed step
- one `$agent_run` at the end, summing up the run

Use the real user ID (and session ID, if you have it) so each run joins the person’s other activity.

```title="POST /api/v1/batch"
{
  "items": [
    {
      "event": "$agent_run",
      "distinct_id": "user_8412",
      "properties": {
        "trace_id": "trc_7f3a91c2d4",
        "run_name": "Summarize ticket",
        "agent_name": "support-bot",
        "source": "helpdesk",
        "outcome": "succeeded",
        "failure_reason": null,
        "started_at": "2026-09-25T14:03:11.402Z",
        "duration_ms": 8120,
        "step_count": 3,
        "tokens_in": 5210,
        "tokens_out": 830
      }
    }
  ]
}
```

### `$agent_run` properties {#run-properties}

| Property | Rule |
| --- | --- |
| `trace_id` | trc\_ followed by 8–60 letters, numbers, \_ or -. The same on the run and its steps. |
| `run_name, agent_name, source` | Text, up to 128 characters. Source is your own label, such as “support-bot”. |
| `outcome` | succeeded, failed or cancelled. failure_reason is text or null. |
| `started_at` | ISO 8601 with an offset. |
| `duration_ms, step_count, tokens_in, tokens_out` | Whole numbers. Up to 200 steps. |

### `$agent_step` properties {#step-properties}

| Property | Rule |
| --- | --- |
| `trace_id, step_id, step_index, parent_step_id` | step_id is stp\_ followed by 1–60 characters. parent_step_id is null at the top level. |
| `type, name` | model or tool, plus a name. |
| `started_offset_ms, duration_ms` | When the step started, relative to the run, and how long it took. |
| `is_error, is_timeout, preview_enabled` | True or false. preview is optional text, kept only when preview_enabled is true. |
| `model, tokens_in, tokens_out, finish_reason` | Model steps only. The model name is what Model prices match. |

Only the properties listed here are accepted on these two events. Until a run arrives, the Traces page shows _No agent runs yet_ with a sample request and a **Check for runs** button.

## Reading Traces {#read}

Open **Traces** under Data. Pick a date range. The page then shows:

- **Runs**, **Finished cleanly**, **Typical run duration** (with the 95th percentile, in wall-clock time) and **Cost**.
- **Runs by outcome** over time.
- A table of runs with their steps, duration and cost.

Narrow the table by searching run or agent names, by trace source, by person, or by outcome (**Succeeded**, **Failed**, **Cancelled**). These narrow the table only: the date range drives the cards and chart too. **Export** downloads the filtered runs as a CSV, with tokens.

## One run {#run}

Click a run to see its **Steps** as a timeline, the output preview if you sent one, what the person did around the run, and who they are.

## Model prices {#prices}

ClickClacks doesn’t guess what a model costs. Runs without a price show a dash, and the page links to **Set model prices**.

1. Open **Settings › Model prices**. Any member can edit it.
2. Enter the **Model** name exactly as your steps send it, such as `openai/gpt-5-mini`.
3. Enter **Input $ per 1M** and **Output $ per 1M** tokens, as your provider lists them.
4. Click **Save model price**.

Run costs use these prices from then on.

## Tips and gotchas {#tips}

- **Model names must match exactly.** `gpt-5-mini` and `openai/gpt-5-mini` are different models to the price list.
- **Send the run event last.** It carries the outcome and totals.
- **Previews are capped** at 400 characters, and a run’s page shows the first 180.

## Recipes {#recipes}

### Which agent fails most, and why?

1. Set the dates to **Last 7 days** and the outcome filter to **Failed**.
2. Search by agent name, and open a few runs to read the failing step.

### What do our agents cost per week?

1. Add a price for every model you use in **Settings › Model prices**.
2. Set the dates to **Last 30 days** and read the **Cost** card.
3. Click **Export** for per-run costs to break down in a spreadsheet.

## Related {#related}

- [Server-side tracking](https://clickclacks.io/docs/api.md): Keys, batches and limits.
- [Sources](https://clickclacks.io/docs/guides/sources.md): Create a server source and key.
- [People and profiles](https://clickclacks.io/docs/guides/people.md)
- [MCP server](https://clickclacks.io/docs/mcp.md)