Import traces from external stores

Importing traces copies a bounded set of runs from an external trace store into an Atlan workspace, so you can inspect them alongside your agents, skills, and sessions; the source store stays the system that recorded them. Use it when the evidence you need already lives in another store. To send new runs as they happen, see Send and verify traces instead.

Before you begin

Before you start, make sure you have:

Access: Read access to the source project, and an identity that can write traces to the target workspace.
Synthetic trace: A non-production trace selected for the first import, with its source trace ID, root operation name, timestamps, expected span count, and final status recorded.
Credentials: The bearer credential in an approved secret store, never in source code, export files, URLs, screenshots, or logs.
Data approval: A decision on which fields may leave the source store. Prompts, completions, tokens, customer data, internal hosts, and production responses need explicit policy approval.

Export source trace

Select one source project and a bounded time range, starting with the synthetic trace so the read-back has a known answer. Export the trace and its spans.

Map trace to OTLP

Build an OTLP ExportTraceServiceRequest that keeps the trace tree and execution facts. Use this mapping as the minimum contract:

Source fact	OTLP representation	Requirement
Trace identifier	`trace_id`	Preserve a valid 128-bit OTLP ID. If the source ID is not valid, derive a deterministic ID and retain the original in an approved, namespaced attribute.
Trace or root operation	Root span	Create one root span for each imported trace so the trace has a stable name, timing, and status.
Span or observation identifier	`span_id`	Preserve or deterministically derive a valid 64-bit OTLP ID.
Parent relationship	`parent_span_id`	Map the source parent through the same identifier conversion so the tree remains intact.
Operation name	Span name	Keep the source operation meaningful and stable.
Start and end time	Span timestamps	Preserve the original execution timing and duration. Do not replace it with import time.
Result or error	Span status and error details	Mark failures as errors. Keep only policy-approved error details.
Source-specific metadata	Attributes	Retain only useful, approved values. Namespace custom keys that do not have an OpenTelemetry semantic-convention key.

Do not infer agent, session, skill, or version attribution from a display name, the source project, or matching timestamps. Send explicit identifiers only when the source and target records establish the relationship.

Send OTLP batch

Send the batch to POST /otel/v1/traces; see the API reference.

Set X-Atlan-Workspace-Id when the import belongs in a specific active workspace. The authenticated identity determines the account; a request cannot select another account.
Send a stable X-Atlan-Ingest-Id for the batch. Reuse it only for an unchanged retry of the same account, workspace, creator, and payload.

A 200 means the batch is accepted and durably queued, not that the trace is readable yet. Keep batches small enough to inspect and retry, and split them only between complete trace trees.

Verify imported trace

Read the trace with GET /registry/v1/users/{user_id}/traces/{trace_id}, where {user_id} is the Atlan user ID of the identity that sent the batch (the id that GET /registry/v1/users/me returns). Confirm that its workspace_id is the intended workspace.
Read its tree with GET /registry/v1/users/{user_id}/traces/{trace_id}/spans. Follow page.next_cursor until it is absent, and check the total against summary.span_count from step 1. Add fields=core,attributes to inspect the retained source metadata.
Compare the root name, span count, parent relationships, timestamps, and final status with the source record.
If the batch is still processing, retry the read within a bounded deadline. Do not send a changed batch while the outcome is unknown; see Import outcome unknown.

Record the source trace ID, target trace ID, workspace, test time, and result in your change record, and remove the synthetic data if your test policy requires it.

Troubleshooting

For 400, 401, 403, 409, 413, timeouts, and a trace that is not found after import, see Trace errors.

Next steps

Import Langfuse traces: Apply this workflow to a Langfuse project.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Import traces from external stores

Before you begin

Troubleshooting

Next steps

See also