> 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.md).

# Traces

REST — Traces endpoints.

| Method | Path                       | Description      |
| ------ | -------------------------- | ---------------- |
| POST   | `/api/v1/traces`           | Ingest one trace |
| POST   | `/api/v1/traces/batch`     | Ingest a batch   |
| GET    | `/api/v1/traces`           | List             |
| GET    | `/api/v1/traces/{id}`      | Get              |
| PATCH  | `/api/v1/traces/{id}/tags` | Tag              |

## Single body

```json
{
 "id": "trace-123",
 "name": "answer-question",
 "inputs": {...},
 "outputs": {...},
 "spans": [...]
}
```

## Idempotency

The trace `id` field is the idempotency key. POSTing the same `id` twice within 24 hours returns the existing trace rather than creating a duplicate. After 24 hours, a re-POST with the same id is treated as a new trace.

For batch ingestion, idempotency applies per-row by trace `id`.

## Validation

The trace payload validates against the [trace JSON Schema](/13.1-sdk-and-apis/trace-schema.md). Validate client-side to catch shape errors before posting.

## See also

* [SDK: traces](/more-in-this-section-9/traces-2.md)
* [Trace JSON Schema](/13.1-sdk-and-apis/trace-schema.md)