---
title: "Edit Trace"
method: PUT
path: "/traces/{trace_id}"
tags: ["Traces"]
---

# Edit Trace

`PUT /traces/{trace_id}`

Replace a trace's spans using the canonical `Trace` shape.

Path `trace_id` must match the `trace_id` inside the payload's
`trace.trace_id`. Mismatches return `400`. The payload must
describe exactly one trace.

Edit re-ingests the spans through the same stream as
`POST /tracing/spans/ingest`. Returns `202 Accepted` once the
spans are queued. The worker reconciles the trace asynchronously.

## Path parameters

- `trace_id` string, required

## Request body

- TraceRequest — Ingest or edit payload for a single canonical `Trace`.
  - `trace` TraceInput
    - `spans` object, nullable
    - `trace_id` string, nullable

## Response `202`

Successful Response

- TraceIdResponse
  - `count` integer — `1` if a `trace_id` was returned, `0` otherwise.
  - `trace_id` string, nullable — 32-char hex UUID identifying the trace that was created or edited.

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-03** `fc532d6dc820` — 6 info
  - added the new optional request property `trace/anyOf[subschema #1: Trace]/spans/anyOf[subschema #1]/additionalProperties/anyOf[subschema #1: SpansNode]/agent_id`
  - added the new optional request property `trace/anyOf[subschema #1: Trace]/spans/anyOf[subschema #1]/additionalProperties/anyOf[subschema #1: SpansNode]/session_id`
  - added the new optional request property `trace/anyOf[subschema #1: Trace]/spans/anyOf[subschema #1]/additionalProperties/anyOf[subschema #1: SpansNode]/user_id`
  - added the new optional request property `trace/anyOf[subschema #1: Trace]/spans/anyOf[subschema #1]/additionalProperties/anyOf[subschema #2]/items/agent_id`
  - …2 more
- **2026-05-19** `a7f9a6823230` — 2 warning
  - removed the optional property `support_id` from the response with the `202` status
  - removed the optional property `support_ts` from the response with the `202` status
- **2026-05-02** `6e37373d45fe` — 2 info
  - api tag `Traces` added
  - api tag `Observability` removed
- **2026-04-23** `925e8b901a26` — 2 info
  - added the optional property `support_id` to the response with the `202` status
  - added the optional property `support_ts` to the response with the `202` status
- **2026-04-18** `c469c2f6cdba` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/agenta-ai/apis/agenta-api/changes/traces/:trace_id/put.md)

---

[API](https://skmtc.dev/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.dev/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/revisions/139f8db295da/schema)