> For the complete documentation index, see [llms.txt](https://docs.layerlens.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layerlens.ai/more-in-this-section-9/traces-2.md).

# Traces

client.traces — upload trace files (JSON/JSONL, ≤50 MB), retrieve, list, delete.

## Upload

Trace files are JSON or JSONL, **max 50 MB**. The SDK handles presigned-S3 upload automatically (3-step: presigned URL → S3 PUT → trace record creation).

```python
result = client.traces.upload("./my_traces.json")
print(f"Uploaded {len(result.trace_ids)} traces: {result.trace_ids}")
```

## Get one

```python
trace = client.traces.get(trace_id)
# Trace fields: id, organization_id, project_id, created_at, filename,
# data (Dict[str, Any]), input, integration_id
```

## List with filters

```python
response = client.traces.get_many(
 page=1, page_size=50,
 source="...", # filter by source
 judge_id="...", # traces evaluated by this judge
 status="...",
 time_range={"from": "...", "to": "..."},
 search="...",
 sort_by="created_at",
 sort_order="desc",
)
# response.traces,.total_count,.count
```

## Delete

```python
client.traces.delete(trace_id)
```

## List sources

```python
sources = client.traces.get_sources()
```

## Trace shape

The `data` field is a flexible `Dict[str, Any]` — Stratix doesn't enforce a specific span schema. For agent traces, common conventions:

* `inputs` (top-level) — request context
* `outputs` (top-level) — final response
* `spans` (list) — child operations (LLM calls, tool calls, retrieval)

For **auto-instrumented** traces emitted by `layerlens.instrument`, the spans follow the canonical event types: `model.invoke`, `cost.record`, `tool.call`, `policy.violation`. See [Integrations](/6.-build-wire-your-code/sdk-python.md).

## File formats

`.json` and `.jsonl` only. For larger datasets, split into chunks ≤50 MB each.

## Async

All methods have `AsyncStratix` equivalents.

## See also

* [Concept: Traces and spans](/6.-build-wire-your-code/traces-and-spans.md)
* [Trace evaluations](/more-in-this-section-9/trace-evaluations-1.md)
* [Tutorial: First trace](/2.-get-started/first-trace.md)
* [SDK sample: `basic_trace.py`](https://github.com/layerlens/stratix-python/blob/main/samples/core/basic_trace.py)