> ## Documentation Index > Fetch the complete documentation index at: https://docs.hue.run/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To set up Hue in an application, fetch https://docs.hue.run/guides/agent-setup.md and follow it. > Hue's project-data MCP server is https://mcp.hue.run/mcp. https://docs.hue.run/mcp only searches these docs and cannot read a Hue project. > Never ask the user to paste a Hue API key into chat; they store it as HUE_API_KEY themselves. > Install the exact SDK versions pinned on the page you're following, or on https://docs.hue.run/quickstart.md. Run the latest CLI without a project install as `npx -y @hue-run/sdk@latest`. In a project with `@hue-run/sdk` installed, use `npx hue`. Pin an exact version for reproducible CI runs. > Use Hue product terms: eval set, case, evaluator, run and scoring run. Older APIs may say dataset, scorer or experiment; prefer the current SDK methods. See https://docs.hue.run/concepts.md. # Bulk import existing traces > Import a bundle of OTLP, Langfuse or ATIF trace exports into a Hue project with one instruction to your coding agent. Bring traces you already hold into a Hue project with one instruction to your coding agent. The agent loads Hue's import guide, runs the import helper on the machine that holds the files, authorizes the delivery through the [Hue MCP server](/agents/mcp-server), uploads the traces and reports what arrived. No project key is involved: your [sign-in connection](/agents/mcp-server#sign-in-with-hue), or a **Read and write** key, authorizes the upload, and the traces go from the helper to Hue, never through the MCP connection. The helper runs with `npx` on the machine that holds the bundle, whatever language your application uses. ## Ask your agent ```text theme={null} Import these traces into my Hue project. ``` Name the file, directory or ZIP archive when it is not in the working directory, and the project when the connection reaches more than one. ## What the agent does 1. **Loads the guide and chooses the project.** `load_hue_guide` with topic `import` describes the workflow. On an organization connection, `list_projects` names the project. 2. **Prepares the bundle on your machine.** `npx -y @hue-run/sdk@latest traces import prepare --out --json` reads the files, writes the prepared import to the directory and prints a report: the manifest digest and totals, the formats it recognized, the files it could not read, invalid vendor ids it mapped deterministically, and the traces without a history owner. Nothing is sent. 3. **Authorizes the delivery.** `prepare_trace_import` with the report's manifest digest, totals and source returns the import id, the upload URL and an authorization valid for a day. The agent writes the authorization to a private file and never pastes it into the transcript, a message or a shell history. 4. **Uploads.** `npx -y @hue-run/sdk@latest traces import upload --authorization-file --json` sends each trace's values and batches in order, two requests at a time, checks every receipt and completes the import. 5. **Reports.** `get_trace_import` with the import id returns the counts and links in [What you get back](#what-you-get-back), and the agent summarizes them for you. ## Supported formats | Format | What the helper reads | | - | - | | OTLP JSON | Files, directories and ZIP archives of OTLP JSON trace exports. | | Langfuse | Complete Langfuse JSON observation exports, in the `data` or the native `observations` envelope. | | ATIF | Text ATIF v1.7 and v1.8 exports, embedded subagents included. | A bundle can mix formats, and the prepare report names each file the helper could not read. One import holds up to 25,000 traces, and one trace up to 512 batches, 100,000 spans and 10,000 large values. ## What you get back `get_trace_import` reports the import's progress and lists its traces. | Field | Meaning | | - | - | | `progress.traces` | Traces declared, verified, held, excluded and conflicted, and the `without_identity` and `unknown_origin` counts. | | `progress.batches`, `progress.blobs` | Batches and large values that still have to land. | | `progress.capture` | Whether each verified trace's evidence reached its owner's [World model](/worlds/overview#worlds-and-traces): retained, unresolved, ineligible or pending. | | `traces` | The traces still pending or conflicting, each with its pending batches and, once stored, its `url` in Hue. `include_verified: true` lists every trace. | A trace is **verified** once every declared batch landed with nothing rejected and every declared value is stored. Only then does it add evidence to its owner's World model; a partial trace adds nothing. Imported traces read like any other: `search_traces` in the traces' own time window, `get_trace`, and `verify_trace` for a receipt. The report also names the gaps: * **Traces without a history owner** (`without_identity`). They import and read like any other trace, but no World model retains their evidence: the report counts them as a history gap and as unresolved. See [Identity](#identity). * **Unknown origin** (`unknown_origin`). The source did not record whether the trace was production, evaluation or simulation traffic. Hue judges those traces from the records' own markers: a trace whose records show evaluation or simulation use never adds to a World model, and the rest add evidence like production traffic. * **Evaluation and simulation traffic.** Traces the source recorded as evaluation or simulation traffic are imported but never add to a World model. `excluded` counts them. * **Conflicts.** A record Hue already holds under the same trace and span id with different content. The stored evidence stays, the batch is reported as conflicted, and resending the same bytes changes nothing. ## Identity A user's World model needs a stable owner per trace. The helper takes it from the source: | Source | Owner | | - | - | | OTLP JSON | A root `user.id`, or explicit `hue.world.entity.namespace` and `hue.world.entity.id` attributes. | | Langfuse | The trace's `userId`. | | ATIF | `extra.user_id`. | Sessions group conversations and never stand in for an owner. App accounts bind separately, through the recorded `hue.connection.*` attributes described in [Worlds and traces](/worlds/overview#worlds-and-traces). ## Resume an interrupted import Run the upload command again. The helper resumes from the progress it saved, and Hue acknowledges the batches it already holds. When the authorization has expired, a day after it was issued, ask your agent to call `prepare_trace_import` again with the same manifest digest and totals: Hue renews the authorization for the same import, and the upload continues. An import stays open for a week after it was prepared, and a renewal within that week extends it. ## Troubleshooting | Problem | Cause and fix | | - | - | | The upload reports that the authorization expired or was replaced | An authorization lasts a day, and each `prepare_trace_import` call replaces the earlier one. Call `prepare_trace_import` again with the same manifest digest and totals, write the newest authorization to the file and run the upload again. | | The upload reports that the connection can no longer write the project | Every upload request checks that the member who approved the import, or the key, still has **Read and write** access to an active project. Connect with one that does and call `prepare_trace_import` again with the same manifest digest and totals. | | `prepare_trace_import` reports that the totals differ | The manifest digest names an import prepared with other totals. Pass the totals the helper printed for this manifest, or prepare the bundle again. | | The import expired | The week to resume it has passed. Ask your agent to call `prepare_trace_import` again with the same manifest digest and totals, which reopens the import for another week, then run the upload command again. | | A trace conflicts with one Hue already holds | Hue keeps the evidence it already stored, and the import does not complete while a trace is unverified. The other traces are verified and stored. Leave the conflicting traces out of the bundle and prepare it again, or keep what Hue holds. | | The helper cannot read the bundle | The prepare report names each unreadable file and the formats it recognized. Export a complete OTLP JSON, Langfuse observation or ATIF v1.7 or v1.8 file, or a directory or ZIP archive of them, and run the prepare command again. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.