Import from Phoenix

Connect Phoenix on the Imports page. Metergraph imports OpenInference spans whose span_kind is LLM, then keeps the selected project level with Phoenix on a schedule.

You may not need this import

The Metergraph SDK’s OpenTelemetry span exporter reads the OpenInference dialect directly, so spans your application already emits can reach Metergraph live, with the SDK’s function attribution intact. If you are still choosing, read OTLP spans first. Import Phoenix history when you want what Phoenix already holds.

What is imported

Phoenix reads spans whose OpenInference span_kind is LLM, from a project through GET /v1/projects/{project}/spans. CHAIN, TOOL, RETRIEVER and AGENT spans are not imported, and annotations and evals are never read.

What you need

Phoenix version	13.15 or newer (phoenix.py, module docstring)
Credential	A Phoenix API key only when the server has authentication on. No key is needed when authentication is off
Scope	A project name or project id, at most 255 characters (import_connections.py, MAX_SCOPE_LENGTH)
Host	Required. Enter your Phoenix Cloud space URL or a self-hosted Phoenix endpoint. There is no hosted default (import_connections.py, SOURCE_POLICIES; imports.js, baseUrlHelp)

The hosted importer stores a supplied credential encrypted and does not need a Metergraph ingest key. A Phoenix server on localhost:6006 is relay-only, because the hosted page cannot reach it (import_egress.py, module docstring).

Phoenix must be 13.15 or newer

Older servers ignore the span_kind query parameter and return every kind of span. The importer filters non-LLM spans locally. The relay also warns how many it dropped, and its --name selector has no effect on an older server (phoenix.py, _is_llm_span).

Connect on the Imports page

1. Select Phoenix

   Open Imports, select Connect, and choose Phoenix.

2. Enter the host and project

   Enter your Phoenix Cloud space URL or a self-hosted Phoenix URL, then enter the project name or id. The project field is limited to 255 characters (import_connections.py, MAX_SCOPE_LENGTH). The URL must be https:// and reachable from the public internet. A private, loopback or plain http:// Phoenix needs the relay appendix (import_egress.py, check_url).

3. Add a key when required

   Enter a Phoenix API key when Phoenix authentication is on. Leave the key blank when the server does not require authentication (imports.js, IMPORT_SOURCES; import_connections.py, SOURCE_POLICIES).

4. Set the range and schedule

   Import from defaults to 7 days ago and cannot be in the future. On hosted Metergraph it cannot be more than 90 days back; a self-hosted operator can set that floor from 1 to 366 days (imports.js, defaultInitialSince; config.py, scheduled_imports_max_backfill_days). Run defaults to Every minute. The picker offers Every minute, Every 5 minutes, Every 15 minutes, Every 30 minutes, Every hour, Every 6 hours and Daily. Phoenix has a 1-minute floor and a one-day ceiling (imports.js, INTERVAL_OPTIONS; import_connections.py, CURSOR_MINIMUM_INTERVAL_SECONDS, MAX_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS).

5. Test and connect

   Optionally select Test connection. Phoenix checks the server, project and key, when one is required, with one page containing at most one span within 6 seconds (phoenix.py, probe, TEST_TIMEOUT_SECONDS). Then select Connect. If the workspace already has a checkpoint for the source and project, the connection resumes from it rather than the start date (api/import_connections.py, create_import_connection).

6. Check the first rows

   On Imports, inspect Imported through, Calls in selected range, Rows pushed per run, Success rate, Next run and Run history. Then open Traces and check the provider, model, tokens, status, route and timestamp.

What lands in Metergraph

Field	Where it comes from
Route	The span’s metergraph.route attribute, then its gen_ai.operation.name, then the span’s own name, then phoenix/backfill. The hosted import has no route override. --route is relay-only
Timestamp	The span’s start_time
Provider and model	Inferred from the span’s OpenInference attributes
Tokens	The span’s OpenInference token attributes, including cache reads, cache writes and reasoning
Latency	Computed from the span’s start and end times
Cost	Left empty because the spans endpoint does not return Phoenix’s UI price. Metergraph prices the row from its catalog
Status	error when the span’s status_code is ERROR, otherwise success
Error type	The span’s status_message
Content	Messages rebuilt from the span’s attributes, including content block text, with raw input and output values as a fallback
Tool names	Extracted from the span’s attributes
Trace, span and parent span	The span’s OpenTelemetry context ids and parent_id
Tags	The project, under phoenix_project

What does not carry over

• Structured tool calls. Tool names come across, but call arguments do not.
• Environment. Phoenix rows arrive with no environment set, so they fall outside any environment filter in the dashboard.
• Function attribution, streaming detail, outcomes and repository identity, as on every import path.
• CHAIN, TOOL, RETRIEVER and AGENT spans, annotations and evals, which are never read.

Caution

Span inputs and outputs are copied verbatim, with no opt-out. Redact at the source before you import if that text may contain personal data.

Troubleshooting

Symptom	Likely cause	What to do
Test connection says “Phoenix wants an API key; this server has authentication on”	Phoenix authentication is on and no key was supplied	Enter a Phoenix API key and test again (phoenix.py, probe)
Test connection says “Phoenix refused the key”	The key is invalid or the server refused it	Check the key and test again (phoenix.py, probe)
Test connection says “Phoenix has no project”	The project name or id does not match a Phoenix project	Check the project list in Phoenix and enter the exact name or id (phoenix.py, probe)
Test connection says “Could not reach Phoenix at”	The base URL is wrong or unreachable	Check the URL and public internet reachability (phoenix.py, probe; import_egress.py)
The endpoint is refused	The hosted egress policy blocks a private, loopback, link-local or metadata address	Use Phoenix Cloud or a public endpoint. A local Phoenix is relay-only (import_egress.py, module docstring)
HTTP 404 naming the project	Relay only: the name or id does not match a Phoenix project	Relay only: check the project list in Phoenix
A warning about non-LLM spans	Relay only: Phoenix is older than 13.15	Relay only: upgrade, or accept that --name has no effect (phoenix.py, _is_llm_span)
Every route is ChatCompletion	Relay only: a standard instrumentor has no route attribute	Relay only: pass --route
Cost is blank on every row	Expected	Metergraph prices these rows itself

Appendix: relay commands

Use the relay for a Phoenix server on a private network, including a local server at localhost:6006, or when you need the relay-only --name and --route options. Set PHOENIX_BASE_URL and, when required, PHOENIX_API_KEY in the relay setup.

Backfill: pull, then push

metergraphrelay pull phoenix --project my-project \
  --since 2026-08-01T00:00:00Z --output phoenix.jsonl
metergraphrelay push phoenix.jsonl

Selector	Meaning
--project	Required project name or id. Repeatable
--name	A span name. Repeatable, and any name matches
--since / --until	Bound span start time. --since is inclusive and --until is exclusive
-n, --count	Caps spans, not traces. The default is 100 (phoenix.py, PAGE_LIMIT)
--route	Relay-only route override

Scheduled: sync

metergraphrelay sync phoenix --source-scope my-project \
  --initial-since 2026-08-01T00:00:00Z --project my-project

--source-scope is a permanent label for the project and selector set. --initial-since seeds only the first run. The relay and hosted paths share a checkpoint for the same source and scope, so do not run both against one scope. The full contract is in the overview appendix.