> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# gateway traces

> List, inspect and export the project's traces, observations and trace sessions from the terminal, land an export in the drive, and import OTLP/JSON exports from other tools.

`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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/cli/files). 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

```bash theme={null}
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

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.