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

# Record telemetry

> Private beta: attach application events to a trajectory.

> [!NOTE]
>
> Private beta. A telemetry event records what happened. A reward is the grader's score.

Use `log_event` during the trajectory. Use `client.telemetry.ingest_events` for events that arrive later, with your organization API key.

## During the trajectory

```python theme={null}
from trajectory import Client

with Client(api_key="<trajectory-api-key>") as runtime:
    runtime.trajectories.log_event(
        "<trajectory-id>",
        event_id="search-result-001",
        name="tool.result",
        payload={"tool": "search", "results": 3},
    )
```

Write runtime events before `complete`. Reuse `event_id` when retrying the same event.
Read them back, newest first, with `client.trajectories.list_events(tid)`.
Events are not reward components. The [source-grader guide](https://docs.trajectory.ai/guides/source-graders.md) logs
grader details as an event; the [diagnostic-artifact guide](https://docs.trajectory.ai/guides/diagnostic-artifacts.md)
attaches a file to a trajectory.

## Later application events

Required fields are `event_id`, `event_type`, `timestamp`, `session_id`, and `source`. Set `trajectory_id` when you have `session.tid`.

```python theme={null}
from datetime import datetime, timezone

from trajectory import Client

events = [
    {
        "event_id": "request-example-001:answer-accepted",
        "event_type": "answer.accepted",
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "session_id": "session-example-001",
        "source": "support-app",
        "trajectory_id": "<trajectory-id>",
        "properties": {"surface": "chat"},
    }
]

with Client() as client:
    result = client.telemetry.ingest_events(events=events)
```

`result` reports `ingested`, `skipped`, and `failures`.


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