Update metadata on a trace after it has been created. Under the hood, this injects a synthetic span through the standard ingestion pipeline — traces remain immutable per the OpenTelemetry spec, and “updating” a trace means adding a span that carries the new attributes. This is useful for attaching labels, user identity, or custom metadata from backend processes that resolve after trace ingestion.
Authentication
Pass your LangWatch API key in the X-Auth-Token header.
Path Parameters
| Parameter | Type | Required | Description |
|---|
traceId | string | Yes | The trace ID to update |
Request Body
{
"metadata": {
"user_id": "user-123",
"customer_id": "cust-456",
"thread_id": "thread-789",
"labels": ["production", "reviewed"],
"custom_key": "custom_value",
"config": { "retries": 3, "timeout": 30 }
}
}
Reserved Fields
| Field | Type | Stored As | Description |
|---|
user_id | string | langwatch.user_id | User identity for analytics |
customer_id | string | langwatch.customer_id | Customer identity for analytics |
thread_id | string | gen_ai.conversation.id | Thread/conversation grouping |
labels | string[] | langwatch.labels | Trace labels for filtering |
Custom Fields
Any key not in the reserved list is stored as metadata.{key} in trace attributes. Custom fields support strings, numbers, booleans, string arrays, and JSON objects.
Merge Semantics
- Attribute accumulation: the synthetic span’s resource attributes are processed through the standard attribute accumulation pipeline — new keys are added, existing keys are updated by the last-write-wins rule
- Labels: the labels array is set as-is on the span resource. If a later span also carries labels, last write wins
- Custom fields: stored as
langwatch.metadata.* resource attributes on the synthetic span
Size Limits
| Limit | Value |
|---|
| Individual metadata value | 4 KB |
| Total metadata payload | 32 KB |
Permissions
Requires traces:update permission on the project.
Response
{
"traceId": "trace-abc-123"
}
Error Responses
| Status | Description |
|---|
| 400 | Empty metadata object, oversized payload, or invalid field values |
| 403 | Missing traces:update permission |
Example
curl -X PATCH https://app.langwatch.ai/api/traces/trace-abc-123/metadata \
-H "X-Auth-Token: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"user_id": "user-456",
"labels": ["reviewed", "production"],
"environment": "staging"
}
}'
Custom metadata keys share the same namespace as metadata set via the SDK during trace ingestion. If both the SDK and this API set the same key, the last write wins.
