gateway traces

gateway traces reads the project’s traces over the public API (GET /api/public/traces, /observations, /sessions) and imports OTLP/JSON exports. Everything except import is read-only. Timestamps and ids print exactly as the API returns them.

List

gateway traces list                                        # newest 50: id, timestamp, name, session, user, tags
gateway traces list --from 2026-09-01T00:00:00Z --limit 500
gateway traces list --session s-42 --tag prod --tag eu --json

Flag	Query parameter
`--from`, `--to`	`fromTimestamp`, `toTimestamp` (ISO 8601).
`--session`, `--user`, `--name`	`sessionId`, `userId`, `name`.
`--tag` (repeatable)	`tags`.
`--environment`	`environment`.
`--order`	`orderBy`: `timestamp.desc` (default) or `timestamp.asc`.
`--limit`	Total traces to print (default 50). The command pages through the API for you.
`--json`	A JSON array of the traces instead of one line each.

no traces match prints on standard error with exit 0.

Get one trace

gateway traces get <traceId>                        # summary: observations, scores, latency, cost
gateway traces get <traceId> --observations          # plus one line per observation
gateway traces get <traceId> --observations --type TOOL --json

GET /traces/{traceId} returns the trace with its observations (input and output included) and scores. Without --observations, --json prints the trace with observationCount in place of the array. --type keeps one observation type: TOOL, GENERATION, SPAN, EVENT, AGENT, CHAIN, RETRIEVER, EVALUATOR, EMBEDDING, GUARDRAIL. A missing trace exits 1 with the API’s message.

Export

gateway traces export traces.jsonl --from 2026-09-01T00:00:00Z
gateway traces export - --session s-42 --observations --type TOOL | jq -c .id
gateway traces export drive:exports/prod-tools.jsonl --tag prod --observations --type TOOL

One JSON object per line. <out> is a file, - for standard output, or drive:<path> to land it in the drive. The filters are the same as list; --limit stops after that many traces (default: every match).

Flag	What it does
`--observations`	Each line carries the trace’s `observations` and `scores`. One `GET /traces/{id}` per trace.
`--type`	With `--observations`: keep only this observation type.
`--limit`	Stop after this many traces.

The summary — wrote N traces (M observations) to <out> — prints on standard error. An export in the drive is an input to gateway worlds data ingest <world> drive:<path> --transform shape.py and gateway worlds data calls pull.

Trace sessions

gateway traces sessions list --from 2026-09-01T00:00:00Z --environment default
gateway traces sessions get <sessionId>           # the session and its traces
gateway traces sessions get <sessionId> --io      # every trace's observations, input and output intact

sessions list reads GET /sessions (--from, --to, --environment, --limit, --json). sessions get reads GET /sessions/{id}; --io adds includeIO=true, the same payload gateway worlds data calls pull --from traces --session <id> reads.

Import OTLP/JSON

gateway traces import export.json --source galileo --world support --task triage
gateway traces import collector.jsonl --attr team=cx
cat export.json | gateway traces import - --dry-run

import posts OTLP/JSON trace exports (one request, a bare resourceSpans array, an array of requests, or JSONL with one request per line) to POST /api/public/otel/v1/traces. The platform normalizes Braintrust, OpenInference (Arize, Phoenix, Galileo), OpenTelemetry GenAI, Langfuse and LangSmith conventions on ingest.

Flag	Resource attribute set
`--source`	`gateway.otel.source`
`--world`, `--world-version`	`gateway.world`, `gateway.world.version`
`--task`	`gateway.task`
`--session`	`gateway.session.id`
`--environment`	`gateway.environment`
`--attr key=value` (repeatable)	that key
`--dry-run`	Parse and count; send nothing.

Flags only add resource attributes; a span’s own attribute wins. The output is { status, batches, spans, resourceAttributes, endpoint }. Input with no spans exits 2; a rejected request exits 1 with the status code.

From code

TypeScript: import { traces } from "@withgateway/sdk" (or @withgateway/sdk/traces) — listTraces, iterateTraces, getTrace, listObservations, iterateObservations, listSessions, iterateSessions, getSession, exportTraces. Python: from gatewaysdk.traces import TracesClient — list, iter, get, observations, iter_observations, sessions, iter_sessions, get_session, export. Both read GATEWAY_HOST, GATEWAY_PUBLIC_KEY and GATEWAY_SECRET_KEY.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

List

Get one trace

Export

Trace sessions

Import OTLP/JSON

From code

​List

​Get one trace

​Export

​Trace sessions

​Import OTLP/JSON

​From code

List

Get one trace

Export

Trace sessions

Import OTLP/JSON

From code