Skip to main content

Update trace

Endpoint: PUT /traces/{trace_id}

Description

Updates filing/sharing metadata (and optionally the display name) on a trace you can edit: you own it, or it is shared with your organization (org_id matches your org) and you belong to that organization. Capture facts — wire trace_id, timing, counts, tokens, cost, input/output, resource attributes, and span payloads — are immutable; there is no span PUT.

All body fields are optional; only sent fields are applied. Explicit null clears a field. An empty body {} returns the current trace without committing changes.

Sharing & filing rules

Changing org_id:

  • Setting org_id to your organization's id shares a personal trace. When you newly share (org_id goes from null to your organization), include project_id in the same request (required — see Introduction — Project). user stays the owner.
  • Setting org_id to null unshares a user-owned trace and removes its project assignment when this key may share it. A private key can unshare a trace it owns. A project-scoped key cannot: once the trace is org-shared, can_share is false and the request returns 403. Spans on the next read have the same org_id. If the trace is still inside an org-shared data collection, unshare is rejected — also pass data_collection_id: null in the same call (or unshare the collection first).
  • Org-only traces (user is null) cannot be unshared and cannot be moved to a different organization.
  • Changing org_id on a trace owned by another user (even if shared with your org) is not allowed — only that user may change org_id for their trace. A private key that sends an org_id receives 400 ("Private API keys cannot change a resource's organization.").
  • Sharing can collide with a pre-existing org row for the same OTLP trace_id (another member already ingested it under org context). That surfaces as 400 ("A trace with this id is already shared with your organization."). Unshare can collide with a pre-existing personal row for the same OTLP trace_id ("A trace with this id already exists for your account.").

Changing data_collection_id:

  • Linking to an org-shared collection forces the trace's org_id to match the collection and inherits the collection's project when one is set. Spans on the next read have the same org_id and data_collection_id.
  • Filing into a personal collection preserves an existing org share.
  • Setting data_collection_id to null detaches the trace from its collection; the trace's org_id is unchanged by the detach unless you also send org_id in the same request (for example org_id: null to detach and unshare together).
  • When both org_id and data_collection_id are sent, org_id must match the target collection's organization.
  • Org-only traces cannot be moved into someone else's personal collection or into a collection in a different organization.

Changing project_id:

  • On a private trace with no data_collection_id, sending project_id alone (without org_id) auto-shares the trace with your organization and assigns it to that project when the key is project-scoped, and only into that key's project. On a private key the field is ignored and the trace stays private.
  • On an org-shared trace not in a data collection, an API key cannot change project_id to a different project, including when the key's owner is an organization admin. That request returns 403. Sending the current project_id again succeeds.
  • You cannot set project_id to null while the trace remains org-shared.
  • A trace linked to a data collection cannot be assigned to a project directly — assign the collection instead (or detach first).

Changing name:

  • Display label only. Surrounding whitespace is stripped; blank or whitespace-only becomes null. Does not change span operation names.

Parameters

  • Path: trace_id — integer row id (not the OTLP hex wire id).
  • Body — application/json:
{
  "name": "string | null",
  "data_collection_id": "integer | null",
  "org_id": "integer | null",
  "project_id": "integer | null"
}

name has no length cap, so an update can store the same label ingest recorded.

data_collection_id, org_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) returns 422 before lookup. JSON null still clears name and each of those ids.

Error responses

  • 401 — Authentication failed.
  • 403 — "You don't have permission to perform this action." — not allowed to update this trace (for example: not the owner of a personal trace, or an API key changing project_id on an already-shared trace, including an organization admin's key), or API key scoping violation.
  • 404 — "Trace with id {trace_id} not found." when the trace is missing or not accessible to your API key. "Data collection not found or access denied." when data_collection_id is missing or not claimable. "Project with id {id} not found." when project_id does not exist.
  • 400 — including:
    • "Organization-owned traces cannot be unshared."
    • "Organization-owned traces cannot be moved to another organization."
    • "Cannot unshare this trace while it remains in an organization-shared data collection. Remove it from the collection first, or unshare the collection."
    • "Private API keys cannot change a resource's organization."
    • "org_id must match your organization."
    • "org_id must match the data collection's organization. A trace's organization is derived from its data collection."
    • "Organization-owned traces cannot be moved to a collection in a different organization."
    • "Organization-owned traces cannot be moved to a personal collection unless the collection is yours."
    • "project_id is required when sharing a resource with your organization."
    • "A trace with this id is already shared with your organization."
    • "A trace with this id already exists for your account."
    • Direct project_id on a trace inside a collection; project_id: null while org-shared; invalid or inaccessible project_id.
    • "Database integrity error." — generic fallback.
  • 422 — Invalid body. data_collection_id, org_id, and project_id must be JSON integers. A digit string ("74"), a whole-number float (1.0), or a boolean (true / false) is rejected before lookup ("Input should be a valid integer"). JSON null is still valid on those ids and on name.
  • 500 — "An error occurred while updating the trace."

Responses

  • 200 — Updated trace object with the same JSON shape as Get trace by id, including permissions for this caller.

curl

Rename a trace:

curl -X PUT "https://api.aegisevals.ai/api/v1/traces/42" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"Checkout agent"}'

Share a personal trace with your organization:

curl -X PUT "https://api.aegisevals.ai/api/v1/traces/42" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"org_id":3,"project_id":5}'

Unshare a user-owned trace:

curl -X PUT "https://api.aegisevals.ai/api/v1/traces/42" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"org_id":null}'

File a trace into a data collection:

curl -X PUT "https://api.aegisevals.ai/api/v1/traces/42" \
  -H "Authorization: Bearer sk_00000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"data_collection_id":7}'