> ## Documentation Index > Fetch the complete documentation index at: https://platform.atlan.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write. > The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects. > SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript. # Import traces from external stores > Copy trace evidence from an external store into Atlan through a repeatable OTLP workflow. Use this cookbook when an external trace store holds the execution evidence you need to inspect alongside Agents, Skills, and sessions in Atlan. It copies a bounded set of traces into the target workspace. The source store remains the system that recorded the run. This page is for the developer who owns the source export and has permission to send OTLP data to the target workspace. ## Before you start * Confirm read access to the source project and write access to the intended Atlan workspace. * Use a non-production, synthetic trace for the first import. Record its source trace ID, root operation name, timestamps, expected span count, and final status. * Keep bearer credentials in an approved secret store. Do not place them in source code, export files, URLs, screenshots, or logs. * Decide which fields may leave the source store. Remove prompts, completions, tokens, customer data, internal hosts, and production responses unless your data-handling policy explicitly permits them. ## Import a trace 1. Select one source project and a bounded time range. Start with the synthetic trace so a later read-back has a known answer. 2. Export the trace and its spans, then build an OTLP `ExportTraceServiceRequest`. Use `POST /otel/v1/traces` from the [API reference](/api/references/api-reference) to ingest the batch. 3. Preserve the trace tree and execution facts in the OTLP payload. Use the mapping below as the minimum contract. 4. 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. 5. 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. | 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 that relationship. A `200` response means the batch is accepted and durably queued. It does not prove that the trace is available in the target workspace. ## Verify the import 1. Read the trace with `GET /otel/v1/traces/{trace_id}` in the intended workspace. Use `fields=summary,attributes` when you need to inspect the retained source metadata. 2. Read its tree with `GET /otel/v1/traces/{trace_id}/spans`. Compare the root name, span count, parent relationships, timestamps, and final status with the source record. 3. If the batch is still being processed, retry the read with a bounded deadline. Do not submit a changed batch while the outcome is unknown. 4. Record the source trace ID, target trace ID, workspace, test time, and verification result in the approved change record. Remove the synthetic data when your test policy requires it. See [Verify trace ingestion](/registry/traces/concepts/verify-ingestion) for the same read-back rule in the product, and [Trace attribution](/registry/traces/concepts/attribution) before asserting that an imported trace belongs to an Agent or Skill. ## Recover safely | Response | What to do | | - | - | | `400` or `422` | Correct the OTLP envelope, identifier conversion, or invalid field before sending a new batch. | | `401` or `403` | Confirm the resolved identity and target workspace access. Do not change the workspace handle to bypass an access boundary. | | `409` | The ingest ID was reused with different facts. Read the prior result, then create a new batch and ingest ID only when required. | | `413` | Reduce the batch at trace boundaries and remove optional, unapproved payload fields. Keep every imported trace tree intact. | | Timeout or `5xx` | Treat delivery as unknown. Read back first, then retry only when the batch is unchanged and idempotent. | For endpoint-specific limits and responses, use the current [OTLP trace-ingestion reference](/api/references/api-reference). ## Add another store Add one child recipe per store. Each recipe should name its source objects, document any identifier or timestamp conversion, list fields excluded by default, and use the verification flow above. Keep common OTLP, security, and read-back guidance on this page so every store follows the same contract. The first recipe is [Import Langfuse traces](/traces/langfuse/how-tos/import-langfuse-traces).