Import from Portkey

Connect Portkey on the Imports page. Metergraph imports Portkey gateway logs through the Logs Export API, then keeps the selected workspace level with Portkey on a schedule. The export-file path remains relay-only.

What is imported

The hosted importer uses Portkey’s Logs Export API. It imports gateway log records, including the provider, model, token counts, cost, latency, status, content and Portkey metadata that the source recorded.

What you need

Credential	A Portkey API key with the logs.export scope
Scope	A workspace id, at most 255 characters. Leave it blank to read the workspace from the key (imports.js, scopeHelp; import_connections.py, MAX_SCOPE_LENGTH)
Host	https://api.portkey.ai/v1 by default. Use another reachable Portkey endpoint when required (import_connections.py, SOURCE_POLICIES)

The hosted importer stores the credential 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 Portkey

   Open Imports, select Connect, and choose Portkey.

2. Enter the key and workspace

   Enter a Portkey API key with the logs.export scope. Optionally enter the Workspace id. If it is blank, Portkey reads the workspace associated with the key (imports.js, IMPORT_SOURCES; import_connections.py, SOURCE_POLICIES).

   If the workspace serves one deployment environment, enter it under Environment, for example production. Every imported call records it, so environment filters can select this traffic. It is at most 128 characters, without spaces. Change it later with Edit settings on the import’s row; calls already imported keep what they had (imports.js, PORTKEY_ENVIRONMENT_FIELD; import_connections.py, _config_environment).

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. The picker offers Every minute, Every 5 minutes, Every 15 minutes, Every 30 minutes, Every hour, Every 6 hours and Daily. Portkey’s floor is 1 minute. Each run creates a Portkey export job, so a longer interval means fewer jobs. The ceiling is one day (imports.js, INTERVAL_OPTIONS; import_connections.py, SOURCE_POLICIES, MAX_INTERVAL_SECONDS, DEFAULT_INTERVAL_SECONDS).

4. Test and connect

   Optionally select Test connection. Metergraph creates a draft export and reads the workspace, with the provider calls bounded by 6 seconds (portkey.py, probe, TEST_TIMEOUT_SECONDS). Then select Connect. If the workspace already has a checkpoint for the source and workspace, the connection resumes from it rather than the start date (api/import_connections.py, create_import_connection).

5. 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 workflow_name in the request’s Portkey metadata. Without one, portkey/backfill. The hosted import has no route override. --route is relay-only
Timestamp	The request’s created_at, kept as the original. A row whose timestamp cannot be read fails 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 (portkey_export.py, cost normalizer)
Latency	The log’s response_time
Status	error when the response status code is 400 or above, or missing (portkey_export.py, status normalizer)
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
Environment	The connection’s Environment setting, when it has one. Portkey logs carry none (portkey_sync.py, convert_portkey_export)

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.
• An environment from the log. Portkey logs carry none, so a call has an environment only when the connection’s Environment setting names one. Without it, Portkey calls fall outside any environment filter in the dashboard.
• Function attribution, streaming detail, outcomes and repository identity, as on every import path.
• A --route override. The hosted path has none. The flag is relay-only. If the route matters, set workflow_name in the Portkey metadata at the source.

Caution

Request and response content from Portkey 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
The key is refused or lacks logs.export	Both paths need a key with the logs.export scope (portkey.py, _failure)	Use a key with that scope. With the relay, an export file downloaded from Portkey needs no key
Test connection says “Could not reach Portkey at”	The base URL is wrong or unreachable	Check the URL and public internet reachability (portkey.py, _failure; import_egress.py)
Waiting on Portkey	Portkey is still preparing the export for a window	Wait for the export or use Sync now. The next run resumes the export (import_runner.py)
The endpoint is refused	The hosted egress policy blocks a private, loopback, link-local or metadata address	Use a public Portkey endpoint, or use the relay appendix (import_egress.py, module docstring)
--source-scope ... only valid in Portkey API cron mode	Relay only: an API flag was passed alongside a file	Relay only: drop the flag, or drop the file
--output is only valid with a local EXPORT_FILE	Relay only: --output was passed in API mode	Relay only: drop it
source scope not set	Relay only: neither --source-scope nor PORTKEY_WORKSPACE is set	Relay only: set one to the workspace id
A window keeps failing on one row	A row the ingest path refuses	Fix the row at the source. The window does not advance past it (import_runner.py)
Every route is portkey/backfill	The requests carry no workflow_name metadata	Set workflow_name in Portkey

Appendix: relay commands

Use the relay for Portkey export files, a Portkey endpoint the hosted importer cannot reach, or a self-operated Metergraph without the operator credentials key. The export-file path never contacts Portkey and needs no Portkey credential.

Export file: convert and upload

Download a JSONL log export from Portkey, then convert and upload it:

metergraphrelay sync portkey export.jsonl

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

metergraphrelay sync portkey export.jsonl --output converted.jsonl
metergraphrelay push converted.jsonl

Export-file rows carry no import identity, so overlapping exports can count a call twice. Track the ranges you have loaded. --source-scope, --initial-since and --max-window-seconds belong to API mode and cannot be used with a file.

Logs Export API

The relay API path uses the same provider endpoint 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
# 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 workspace id and must not change. It falls back to PORTKEY_WORKSPACE. --output belongs to export-file mode. 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.