Import from Portkey

Do the shared setup first: an ingest key, pip install metergraphrelay, and a .env holding METERGRAPH_APP_TOKEN.

Portkey is the one source with two routes in, and which one you take depends on your Portkey plan.

	Export file	Logs Export API
What it needs	A JSONL log export you download yourself	A Portkey key with the logs.export scope, an Enterprise feature
Contacts Portkey	No	Yes
Runs on a schedule	No	Yes, hourly from cron
Deduplicates re-read rows	No	Yes

Both are spelled metergraphrelay sync portkey. Passing a file selects the export path. Omitting one selects the API path. There is no metergraphrelay pull portkey.

Export file

Download a JSONL log export from Portkey, then convert and upload it. This never contacts Portkey and needs no Portkey credential.

1. Export the logs from Portkey

   Use Portkey’s own log export. You need a Portkey subscription with log export enabled.

2. Convert and upload

   metergraphrelay sync portkey export.jsonl

   With no --output the converted file is a private temporary file, removed after the upload. Pass --output to keep it, including when the upload fails:

   metergraphrelay sync portkey export.jsonl --output converted.jsonl
   metergraphrelay push converted.jsonl   # retry the upload on its own

   The command prints one line: how many rows it converted, how many it skipped, how many it pushed, and how many failed.

Export file rows are not deduplicated

Only the API path stamps an import identity on each row. Rows from an export file carry none, so importing overlapping exports counts the same call twice. Keep track of which ranges you have already loaded.

--source-scope, --initial-since and --max-window-seconds belong to the API path. Passing one alongside a file is an error rather than a silent no-op.

Logs Export API

With a Portkey key carrying the logs.export scope, the relay pulls windows itself and can run from cron.

.env

METERGRAPH_APP_TOKEN=<your ingest key>
PORTKEY_API_KEY=<a key with the logs.export scope>
# PORTKEY_WORKSPACE=ws-acme      # or pass --source-scope on every run
# PORTKEY_BASE_URL=https://api.portkey.ai/v1

metergraphrelay sync portkey --source-scope ws-acme --initial-since 2026-08-01T00:00:00Z

--source-scope is the Portkey workspace id. It is not a secret, and it is also what names the checkpoint on the Metergraph side, so it must never change. It falls back to PORTKEY_WORKSPACE. One Portkey workspace maps to one Metergraph workspace.

--output belongs to the export-file path, and passing it here is an error.

The window, overlap, lease and exit code contract is the same as every other source: see How ongoing sync works.

What lands in Metergraph

Field	Where it comes from
Route	The workflow_name in the request’s Portkey metadata. Without one, portkey/backfill
Timestamp	The request’s created_at, kept as the original. A row whose timestamp cannot be read fails the conversion rather than being re-dated
Provider	The log’s ai_org
Model	The log’s ai_model
Input and output tokens	The log’s req_units and res_units
Cost	The log’s cost, converted from cents to dollars
Latency	The log’s response_time
Status	error when the response status code is 400 or above, or missing
Error type	The response’s error message
Content	The request and response from the export, copied verbatim
Tool calls and tool names	Extracted from the response
Trace and span	The log’s trace_id and its own id
Tags	The whole Portkey metadata object

What does not carry over

• Cache and reasoning token buckets. Portkey logs carry a request and a response unit count and nothing finer, so those columns stay empty.
• Environment. Portkey 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.
• A --route override. Neither Portkey path accepts one. If the route matters, set workflow_name in the Portkey metadata at the source.

Caution

Request and response content from the export is copied verbatim, with no opt-out, on both paths. Redact at the source before you import if that text may contain personal data.

Troubleshooting

Symptom	Likely cause	What to do
API mode is rejected at authorization	The key lacks logs.export, an Enterprise scope	Use the export-file path
--source-scope ... only valid in Portkey API cron mode	An API flag was passed alongside a file	Drop the flag, or drop the file
--output is only valid with a local EXPORT_FILE	--output was passed in API mode	Drop it
source scope not set	Neither --source-scope nor PORTKEY_WORKSPACE is set	Set one to the workspace id
A window keeps failing on one row	A row the ingest API refuses	Fix the row at the source. The window will not advance past it
Every route is portkey/backfill	The requests carry no workflow_name metadata	Set it in Portkey