Import from Langfuse

Connect Langfuse on the Imports page. Metergraph imports GENERATION observations from the Langfuse v2 Observations API, and the evaluation scores written on them, then keeps the selected project level with Langfuse on a schedule. The hosted form has no trace-name or tag selector.

The same connection is how you bring a Langfuse LLM judge and a dataset into Metergraph to judge a model swap. Those are imported on request, not on the schedule: see Judge model swaps with your Langfuse evals.

What is imported

Langfuse GENERATION observations are records of individual model calls, read through GET /api/public/v2/observations. Langfuse Cloud and self-hosted Langfuse v4 or newer work (langfuse.py, fetch_page). SPAN and EVENT observations are never read.

Evaluation scores are read on their own schedule through the Langfuse Scores API v3 (GET /api/public/v3/scores) and attached to the trace, observation, session or experiment they belong to. Trace and observation scores show in trace detail. They are imported as scores, never as Metergraph evaluations, and a score outage does not mark the generation import as failed (langfuse_score_sync.py).

Prompt and response text is imported only when you tick Import prompts and responses on the connection. Without it every call arrives without its request and response, and Metergraph can neither show nor analyze that text (imports.js, CONTENT_OPT_IN_FIELD; import_connections.py, CONTENT_OPT_IN).

What you need

Credentials	A Langfuse project’s public key (pk-lf-...) and secret key (sk-lf-...)
Scope	A stable project label. It keys the checkpoint, so do not change it (imports.js, scopeHelp)
Environment	Optional. Blank means all environments (imports.js, langfuse.fields)
Host	https://cloud.langfuse.com, Langfuse Cloud EU, by default. Use https://us.cloud.langfuse.com for Langfuse Cloud US, or a self-hosted v4 or newer endpoint (import_connections.py, SOURCE_POLICIES; imports.js, baseUrlHelp)

The hosted importer stores the secret key encrypted and does not need a Metergraph ingest key. The relay appendix is the path that uses an ingest key (import_providers/__init__.py, module docstring).

Connect on the Imports page

1. Select Langfuse

   Open Imports, select Connect, and choose Langfuse.

2. Enter the key pair and scope

   Enter the Public key first, then the Secret key. Enter a stable Project label for the Langfuse key pair. Optionally enter an Environment to import only observations from that environment. The hosted import sends no trace-name or tag selector (imports.js, langfuse.fields; langfuse.py, make_pull_window). Tick Import prompts and responses to copy each call’s request and response text. It is off by default.

3. 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. Langfuse accepts Every minute, Every 5 minutes, Every 15 minutes, Every 30 minutes, Every hour, Every 6 hours and Daily. Its floor is 1 minute and the ceiling is one day (imports.js, INTERVAL_OPTIONS; import_connections.py, CURSOR_MINIMUM_INTERVAL_SECONDS, MAX_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS).

4. Set the host when needed

   Leave API base URL blank for Langfuse Cloud EU at https://cloud.langfuse.com. Open Self-hosted Langfuse to enter https://us.cloud.langfuse.com for Langfuse Cloud US or your own Langfuse v4 or newer endpoint. A self-hosted endpoint must be https:// and reachable from the public internet (imports.js, baseUrlHelp; import_egress.py, check_url).

5. Test and connect

   Optionally select Test connection. Langfuse checks one generation from the last hour, or from the start date when that is more recent, within 6 seconds (langfuse.py, probe, TEST_TIMEOUT_SECONDS). Then select Connect. Metergraph does not contact Langfuse during Connect. If a checkpoint already exists for this project label, the new connection resumes from it rather than the start date (api/import_connections.py, create_import_connection).

6. Check the first rows

   On the connection row, 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 Langfuse trace name, then the generation’s own name. The hosted import has no route override. --route is relay-only
Timestamp	The observation’s startTime
Provider and model	Inferred from the observation’s model field
Input tokens	The named input total plus every other input bucket Langfuse reported, so it is the whole prompt
Output tokens	The same rollup on the output side
Cache reads, cache writes, reasoning	Langfuse’s own buckets, wherever the integration recorded them
Cost	Langfuse’s totalCost
Status	error when the observation’s level is ERROR, otherwise success
Error type	The observation’s statusMessage
Content	Input and output, only when Import prompts and responses is ticked. They then follow your workspace’s content-capture policy, as SDK calls do
Scores	Each evaluation score, on the trace or observation it was written on, with its source, comment and metadata
Trace, span and parent span	The Langfuse trace id, observation id and parent observation id
Session	The observation’s sessionId
Environment	The observation’s environment
Tags	Langfuse trace tags, under langfuse_tags

What does not carry over

• Latency. The importer reads the observation’s start time only, so an imported Langfuse row has no latency_ms. This is the one supported source where that is true.
• Tool calls and tool names.
• Function attribution, streaming detail, outcomes and repository identity, as on every import path.
• Spans and events, which are never read.
• Evaluator definitions and datasets, which the schedule never reads. Import them on request, as Judge model swaps with your Langfuse evals describes.

Caution

With Import prompts and responses ticked, prompt and response text is copied into Metergraph. Redact at the source before you tick it if that text may contain personal data.

Troubleshooting

Symptom	Likely cause	What to do
Test connection says “Langfuse refused the key pair”	The public and secret keys do not form a readable project key pair	Check both fields and the project’s permissions, then test again (langfuse.py, probe)
Test connection says “Could not reach Langfuse at”	The host is wrong or unreachable	Check the base URL and make sure it is reachable from the public internet (langfuse.py, probe; import_egress.py)
A self-hosted Langfuse rejects the request	Langfuse is older than v4	Upgrade. The v2 Observations API is required (langfuse.py, fetch_page)
Cache or reasoning columns are empty	The integration never recorded those buckets	Nothing to fix. The totals are still right
Every route is the generation name rather than a workflow	Relay only: the traces carry no name	Relay only: pass --route when you run metergraphrelay pull or sync
A pull returns 0 rows just after a run	Relay only: Langfuse has not made the observations readable yet	Relay only: wait, then rerun
The endpoint is refused	The hosted egress policy blocks a private, loopback, link-local or metadata address	Use a public endpoint, or use the relay appendix for a source the hosted importer cannot reach (import_egress.py, module docstring)

Appendix: relay commands

Use the relay for a Langfuse instance that the hosted importer cannot reach, or when you need relay-only trace-name and tag selectors. The relay default is also https://cloud.langfuse.com, which is Langfuse Cloud EU. Set LANGFUSE_BASE_URL or pass --base-url for another host (metergraphrelay/providers/langfuse.py, DEFAULT_LANGFUSE_HOST).

Backfill: pull, then push

After the relay setup, choose selectors and write a local JSONL file. Then inspect and upload it.

metergraphrelay pull langfuse --trace-name support-bot --tag prod \
  --since 2026-08-01T00:00:00Z --until 2026-08-08T00:00:00Z \
  --output langfuse.jsonl
metergraphrelay push langfuse.jsonl

The selector table is relay-only:

Selector	Meaning
--trace-name	A Langfuse trace name. Repeatable, and any name matches
--tag	A trace tag. Repeatable, and all tags must be present
--environment	One Langfuse environment value
--since / --until	Bound observation start time. --since is inclusive and --until is exclusive
-n, --count	Caps observations, not traces. The default is 100 (langfuse.py, PAGE_LIMIT)
--route	Relay-only route override

Scheduled: sync

metergraphrelay sync langfuse --source-scope support-bot-prod \
  --initial-since 2026-08-01T00:00:00Z --trace-name support-bot --tag prod

--source-scope is a permanent checkpoint label and must not change. --initial-since seeds only the first run. The relay sync and hosted connection share one checkpoint for the same source and scope, so do not run both against one scope. The full window, overlap, lease and exit-code contract is in the overview appendix.