---
title: "Edit Trace"
method: PUT
path: "/tracing/traces/{trace_id}"
tags: ["Deprecated"]
deprecated: true
---

# Edit Trace

`PUT /tracing/traces/{trace_id}`

> **Deprecated.**

Replace the spans of an existing trace.

The path `trace_id` must match the `trace_id` in the payload.
Mismatches return `400`. The payload must contain exactly one
trace; submitting spans from more than one trace returns `400`.

Edit is implemented as a re-ingest: the new spans are written
through the same stream as `POST /tracing/spans/ingest`, and the
`202 Accepted` response reports how many spans entered the stream.
The worker reconciles the trace asynchronously.

## Path parameters

- `trace_id` string, required

## Request body

- OTelTracingRequest — Ingest or query payload for OpenTelemetry-style spans. Exactly one of `spans` or `traces` should be provided. Use `spans` for a flat list (parent/child linked via `parent_id`); use `traces` for a nested tree (keyed by `trace_id` then by span name, children hanging off each node's `spans` field). The two shapes are interchangeable and the query endpoint returns the `traces` shape by default. See [Tracing](/reference/api-guide/tracing) for the full attribute namespace and the async ingest contract.
  - `spans` SpanInput[], nullable — Flat list of spans. Use this when you already have a flat list and parent/child relationships are expressed via each span's `parent_id`.
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `deleted_at` string, date-time, nullable
    - `created_by_id` string, uuid, nullable
    - `updated_by_id` string, uuid, nullable
    - `deleted_by_id` string, uuid, nullable
    - `trace_id` string, required
    - `span_id` string, required
    - `parent_id` string, nullable
    - `trace_type` 'invocation' | 'annotation' | 'unknown'
    - `span_type` 'agent' | 'chain' | 'workflow' | 'task' | 'tool' | 'embedding' | 'query' | 'llm' | 'completion' | 'chat' | 'rerank' | 'unknown'
    - `span_kind` 'SPAN_KIND_UNSPECIFIED' | 'SPAN_KIND_INTERNAL' | 'SPAN_KIND_SERVER' | 'SPAN_KIND_CLIENT' | 'SPAN_KIND_PRODUCER' | 'SPAN_KIND_CONSUMER'
    - `span_name` string, nullable
    - `start_time` union
      - string, date-time
      - integer
    - `end_time` union
      - string, date-time
      - integer
    - `status_code` 'STATUS_CODE_UNSET' | 'STATUS_CODE_OK' | 'STATUS_CODE_ERROR'
    - `status_message` string, nullable
    - `session_id` string, nullable
    - `user_id` string, nullable
    - `agent_id` string, nullable
    - `attributes` object, nullable
    - `references` OTelReferenceInput[], nullable
      - `version` string, nullable
      - `slug` string, nullable
      - `id` string, uuid, nullable
      - `attributes` object, nullable
    - `links` OTelLinkInput[], nullable
      - `span_id` string, nullable
      - `trace_id` string, nullable
      - `attributes` object, nullable
    - `hashes` OTelHashInput[], nullable
      - `id` string, uuid, nullable
      - `attributes` object, nullable
    - `exception` object, nullable
    - `events` OTelEventInput[], nullable
      - `name` string, required
      - `timestamp` union, required
        - string, date-time
        - integer
      - `attributes` object, nullable
  - `traces` object, nullable — Nested tree of spans keyed by `trace_id` → span name, with children under each node's `spans` field. This matches the shape returned by `POST /tracing/spans/query` with `focus="trace"`.

## Response `202`

Successful Response

- OTelLinksResponse — Response from span ingestion. `count` reflects how many spans were successfully parsed and published to the ingest stream. If you submitted N spans and see `count < N`, some spans failed server-side validation and were not persisted (check server logs for details). See [Tracing — Async write contract](/reference/api-guide/tracing#async-write-contract-202) for the full semantics of the `202 Accepted` response.
  - `count` integer — Number of spans that were accepted and published to the ingest stream. Compare against the number of spans you sent to detect partial failures.
  - `links` OTelLinkOutput[], nullable — List of `(trace_id, span_id)` pairs for the accepted spans, in submission order.
    - `span_id` string, nullable
    - `trace_id` string, nullable
    - `attributes` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agenta-ai/apis/agenta-api.md) · [All operations](https://skmtc.net/agenta-ai/apis/agenta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agenta-ai/agenta-api/versions/2e1079696f45/schema)