Skip to main content
POST
Create trace deletion request

Authorizations

x-api-key
string
header
required

Headers

x-selected-account-id
string | null

Body

application/json
reason_code
enum<string>
required
Available options:
customer_requested_deletion
trace_ids
string[]
required

Explicit trace IDs to delete. Limited to 10,000 after deduplication.

Required string length: 1 - 256
reason_details
string | null

Optional bounded audit context for the deletion request.

Maximum string length: 2000
group_id
null

Response

Successful Response

deletion_request_id
string
required
status
enum<string>
required
Available options:
accepted,
resolving,
deleting,
completed,
failed,
canceled
object
string
default:trace_deletion
trace_count
integer | null
resolved_trace_count
integer | null
tombstoned_span_count
integer | null

Live spans tombstoned in the tracing service, from the awaited propagation acknowledgement. Response-only (the durable record is sgp-traces' deletion audit). Null when propagation was skipped or ran best-effort. The tracing service applies its deletion cutoff per storage engine. On ClickHouse deployments this counts the identities live among the rows ingested at or before the cutoff and masks exactly those rows. On Postgres deployments an identity is one row whose ingested_at its latest write refreshed, so it counts identities whose latest write is at or before the cutoff: a span whose in-progress precursor was ingested before the cutoff and whose completion landed after it counts 1 on ClickHouse and 0 on Postgres. In this order both engines still serve the completion, so only the count differs; the reverse order, a lower-version write landing after the cutoff, also differs in read visibility. The cutoff is the deletion's arrival at the tracing service, so this is a race with an in-flight completion. On ClickHouse deployments a lower-version write of a span that lands after the cutoff is a second row: the deletion removes only the rows ingested at or before the cutoff and point reads then serve the surviving lower-version row. On Postgres deployments the upsert guard rejects a lower-version write while the row is live, so the one row keeps its pre-cutoff ingested_at, is masked, and no read serves the span. Both engines count the span once here. Only a write landing after the mask, when the masked row admits any version, behaves the same on both engines. On ClickHouse deployments a repeat deletion of traces an earlier audit already covers reports 0: its live count excludes every row ingested at or before the earlier audit's reach, whether or not that mask completed. On Postgres deployments the count is the rows still live at or before the cutoff, so a retry after a failed mask reports the rows it masks.

soft_deleted_at
string<date-time> | null