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

# Logs & Trace Explorer

> Query authoritative production traces, inspect model and tool evidence, aggregate failures, and route selected traces into governed evaluation workflows.

Logs & Trace Explorer is the production investigation workspace for traces, spans, model calls, costs, tools, scores, evidence, online alerts, and review state. It provides one bounded query language and one virtualized result table without creating a second copy of trace payloads.

<Info>
  The explorer derives each row from the platform's authoritative trace, span, model-call ledger, cost, judge, tool-evidence, policy, evidence, online-evaluation, and adjudication records. Saved views, cohorts, tags, action receipts, and export audits store configuration or workflow state only; they do not duplicate semantic trace payloads.
</Info>

## Recommended investigation workflow

<Steps>
  <Step title="Start with a bounded failure query">
    Filter by status, environment, provider, model, tool error, deployment or prompt version, cost, latency, score, alert, review state, provenance, or tag. Use free text only after structured filters have narrowed the result set.
  </Step>

  <Step title="Group the result set">
    Group by status, environment, provider, model, failure category, alert state, review state, provenance, or tag. Compare count, known cost, average duration, p95 model latency, and average score without leaving the current query.
  </Step>

  <Step title="Inspect the trace">
    Open a row and move between Tree, Timeline, Thread, Input / Output, Tools, Scores, Cost, Evidence, and Review. Each section reads the underlying records on demand. When a collection has more than 100 records, use its **Load more** control until the continuation is complete.
  </Step>

  <Step title="Preserve the investigation">
    Save personal, project, or organization views when table layout matters. Save a cohort when another workflow needs to reuse the query as a named population.
  </Step>

  <Step title="Route evidence into action">
    Select traces and add them to Dataset Hub, open them in an evaluation Playground, create candidate cases or review tasks, tag or compare them, or create a draft online monitor from the current query. Simulate and explicitly activate that draft in Continuous Eval before it samples live traffic.
  </Step>

  <Step title="Export only when necessary">
    Export a bounded redacted CSV or JSONL file. Raw export is an explicit privileged operation and every export attempt is audited.
  </Step>
</Steps>

## Query language

Queries are case-insensitive for `AND` and use one clause per field. Values containing whitespace or punctuation can be quoted. The service parses the query, validates the field/operator pairing and value type, and returns canonical query text. Use the returned text for bookmarks, saved views, pagination, monitor creation, and exports.

```text theme={null}
status = failed AND environment = production AND provider = openai
tool_name = checkout AND tool_error ~ timeout
cost_usd >= 0.05 AND latency_ms > 2000
model in (gpt-4.1, claude-sonnet-4) AND provenance = incomplete
text ~ "card authorization" AND created >= 2026-07-01T00:00:00.000Z
```

### Fields

| Category          | Fields                                                                                   | Derived from                                               |
| ----------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Trace identity    | `created`, `trace_name`, `trace_id`, `status`, `environment`, `source`                   | Trace record                                               |
| Actor and release | `session`, `user`, `prompt_version`, `deployment_version`                                | Trace metadata                                             |
| Model execution   | `provider`, `model`, `backend`, `latency_ms`, `tokens`, `provenance`, `failure_category` | Model-call ledger                                          |
| Tools             | `tool_name`, `tool_error`                                                                | Tool invocation evidence                                   |
| Performance       | `duration_ms`, `cost_usd`, `score`                                                       | Trace, cost records, and scores                            |
| Workflow          | `alert_status`, `review_status`, `tag`                                                   | Online alerts, adjudication, and explorer tags             |
| Payload search    | `text`                                                                                   | Trace name/key, span input/output, and model-call previews |

### Operators

| Operator             | Meaning               | Notes                        |
| -------------------- | --------------------- | ---------------------------- |
| `=`                  | Equals                | Valid for every typed field  |
| `!=`                 | Does not equal        | Valid for every typed field  |
| `>`, `>=`, `<`, `<=` | Ordered comparison    | Numeric and date fields only |
| `~` or `:`           | Contains              | String fields and `text`     |
| `in (...)`           | One of several values | Up to 20 values              |
| `exists`             | Has a non-null value  | Does not take a value        |

The query is limited to 2,000 characters, 20 structured filters, and 200 free-text characters. A page contains at most 100 traces. Invalid fields and operators return a specific `INVALID_FIELD` or `INVALID_OPERATOR` response; excessive expressions return `QUERY_TOO_COMPLEX` instead of running an unbounded database query.

### Stable pagination

The first sort defaults to newest creation time. Supported primary sorts are creation time, trace duration, known cost, score, and maximum model latency. The cursor binds the organization, canonical query hash, sort field, direction, value, creation time, and trace database identifier. Reusing it with a different organization, query, or sort returns `INVALID_CURSOR`.

## Results workspace

The table can show Created, Trace, Input, Output, Status, Environment, Duration, Cost, Model, Tools, Score, Failure, Alert, Review, and Provenance. Choose up to three pinned columns. The table renders only the visible row window plus a small overscan region, so loading thousands of results does not create thousands of DOM elements.

Keyboard controls are available directly on the result list:

* Up and Down move the active row;
* Space selects or clears the active row;
* Enter opens trace detail;
* Escape closes detail.

The footer reports loaded rows, the visible range, keyboard help, evidence status, and whether another cursor is available. Unknown cost remains **Unknown**, missing scores remain empty, and incomplete provenance is visibly distinct from complete provenance. Missing values are never silently converted to zero.

## Aggregation

The same canonical query can be grouped by up to two fields. Available metrics are:

| Metric         | Semantics                                                     |
| -------------- | ------------------------------------------------------------- |
| `count`        | Number of matching traces                                     |
| `sum_cost`     | Sum of known cost values; unknown cost is not treated as zero |
| `avg_duration` | Mean of known trace durations                                 |
| `p95_latency`  | Nearest-rank p95 of known maximum model-call latency          |
| `avg_score`    | Mean of known trace scores                                    |

Aggregations execute over the complete authorized predicate and return `scannedRows`, `complete`, and `truncated` with every result. The workspace labels a successful result as **Exact across *n* traces**; it never presents a safety-bound sample as a whole-population total. Aggregation database work has a 15-second execution budget. If that budget is exceeded, the request fails with `QUERY_TOO_COMPLEX` instead of returning a partial total.

## Trace detail

Each detail mode uses the authoritative organization-scoped records associated with the trace:

| Section        | Evidence shown                                                                              |
| -------------- | ------------------------------------------------------------------------------------------- |
| Tree           | Parent/child spans and linked model calls                                                   |
| Timeline       | Ordered spans with duration and timing                                                      |
| Thread         | Conversation-like span inputs and outputs                                                   |
| Input / Output | Full projected span payloads                                                                |
| Tools          | Tool name, operation, request/response preview, policy decision, latency, status, and error |
| Scores         | Linked judge results and reasoning                                                          |
| Cost           | Cost records linked through spans or model-call ledger rows                                 |
| Evidence       | Evidence items, model provenance, and policy decisions                                      |
| Review         | Online alerts and adjudication tasks for the trace                                          |

Each related collection is limited to 100 records per request. When more records exist, `nextCursors` contains a continuation cursor for that collection and `truncated` remains `true`. Request the same trace and section with both `collection` and `cursor`; append the returned records, then continue until that collection's cursor is `null`. A cursor is bound to the authenticated organization, trace, section, collection, and typed last identifier. Reusing it across any of those boundaries returns `INVALID_CURSOR`.

## Saved views and cohorts

A saved view keeps the canonical query, selected and pinned columns, grouping, sort, owner, scope, and default preference.

* **Personal** views can be read and changed only by their owner.
* **Project** views are readable within the organization and manageable by their owner.
* **Organization** views are readable within the organization; only organization administrators and owners can create or manage them.

Share URLs include only the canonical query, view identifier, and safe column configuration. They never grant raw-payload permission or transfer organization authority. Opening a shared URL still performs normal authentication and organization checks.

Select a view to restore its exact query, columns, pins, and primary sort. The adjacent controls copy the server-produced safe share URL or delete an authorized view. Change the name, scope, query, layout, or sort and choose **Update saved view** to revise it in place.

A cohort is a named, organization-scoped canonical query. Cohorts are intended for reusable populations such as “production tool timeouts,” “high-cost incomplete traces,” or “reviewed checkout failures.” Owners can update or delete their cohorts; organization administrators and owners can manage any cohort in the organization.

## Bulk actions

Select up to 100 traces for a bulk workflow. Every mutating action requires an idempotency key scoped by organization and action type. Replaying the same key with the same request returns the stored result. Reusing it with different content returns `IDEMPOTENCY_CONFLICT`.

| Action             | Result                                                                                                                  | Required permission             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| Add to dataset     | Creates Dataset Hub rows with trace source provenance                                                                   | Trace read and evaluation write |
| Open in Playground | Creates or reuses trace-origin test cases and returns the evaluation Playground URL                                     | Trace read and evaluation write |
| Create candidate   | Creates deduplicated candidate evaluation cases                                                                         | Trace read and evaluation write |
| Create review      | Creates adjudication tasks linked to `trace:<id>`                                                                       | Trace write                     |
| Tag                | Adds organization-validated trace tags                                                                                  | Trace write                     |
| Compare            | Returns the selected rows and duration, cost, and score deltas from the first trace                                     | Trace read                      |
| Create monitor     | Creates a draft online monitor and freezes the selected saved view's complete canonical predicate and hash when present | Organization admin              |

Bulk responses contain one item per requested trace. A trace from another organization is reported as `not_found`; its existence is not disclosed. Partial success remains visible beside the action and can be retried with a new key after the input is corrected.

## Redaction, retention, and raw access

Normal query, detail, and export responses pass payload-bearing fields through the Logs Explorer redaction projection. It recursively masks common secrets and credentials and truncates oversized values. Raw content requires both an organization administrator or owner role and the explicit `admin:org` scope.

<Warning>
  Raw permission does not override retention. If trace metadata marks payload retention as expired, or `payloadExpiresAt` is in the past, payload fields return `[PAYLOAD EXPIRED]` for every caller and export mode.
</Warning>

Requests for raw content are explicit (`raw: true`). Share URLs and saved views do not persist raw mode. Query responses and exports use private, no-store caching semantics where payloads are returned.

## Exports

Exports support CSV and JSONL, at most 5,000 rows and 5 MiB. Every attempt records organization, actor, canonical query hash, format, raw request state, redaction state, status, row count, byte count, and completion time. The response includes the audit identifier, row count, and truncation state in headers.

Use the platform UI for interactive investigation. Use an export only when another authorized system needs a bounded snapshot.

## API reference

All routes derive the organization and actor from authenticated context. Supplying an organization identifier in a query string or request body never changes scope.

| Method                   | Endpoint                                                 | Purpose                                                    | Required scope                    |
| ------------------------ | -------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------- |
| `GET`                    | `/api/logs/traces?q=&cursor=&limit=&raw=`                | Query traces with URL parameters                           | `traces:read`                     |
| `POST`                   | `/api/logs/query`                                        | Query with canonical text or structured filters            | `traces:read`                     |
| `GET`                    | `/api/logs/traces/:traceId?section=&collection=&cursor=` | Read one detail section or continue one related collection | `traces:read`                     |
| `POST`                   | `/api/logs/aggregate`                                    | Group and aggregate the current population                 | `traces:read`                     |
| `GET`, `POST`            | `/api/logs/views`                                        | List or create saved views                                 | `traces:read` / `traces:write`    |
| `GET`, `PATCH`, `DELETE` | `/api/logs/views/:viewId`                                | Read or manage a saved view                                | `traces:read` / `traces:write`    |
| `GET`, `POST`            | `/api/logs/cohorts`                                      | List or create reusable cohorts                            | `traces:read` / `traces:write`    |
| `GET`, `PATCH`, `DELETE` | `/api/logs/cohorts/:cohortId`                            | Read or manage a cohort                                    | `traces:read` / `traces:write`    |
| `POST`                   | `/api/logs/actions/add-to-dataset`                       | Route selected traces to Dataset Hub                       | `traces:read`, `eval:write`       |
| `POST`                   | `/api/logs/actions/open-in-playground`                   | Route selected traces to an evaluation Playground          | `traces:read`, `eval:write`       |
| `POST`                   | `/api/logs/actions/create-candidate`                     | Create candidate evaluation cases                          | `traces:read`, `eval:write`       |
| `POST`                   | `/api/logs/actions/create-review`                        | Create adjudication tasks                                  | `traces:write`                    |
| `POST`                   | `/api/logs/actions/create-monitor`                       | Create an online monitor from a query                      | `admin:org`, admin role           |
| `POST`                   | `/api/logs/actions/tag`                                  | Tag selected traces                                        | `traces:write`                    |
| `POST`                   | `/api/logs/actions/compare`                              | Compare selected traces                                    | `traces:read`                     |
| `POST`                   | `/api/logs/export`                                       | Create an audited CSV or JSONL export                      | `traces:read`, `exports:download` |

### Query request

```json theme={null}
{
  "query": "status = failed AND environment = production AND tool_error ~ timeout",
  "sort": [{ "field": "created", "direction": "desc" }],
  "limit": 100,
  "raw": false
}
```

Alternatively, send `filters` and `freeText` instead of `query`:

```json theme={null}
{
  "filters": [
    { "field": "status", "operator": "eq", "value": "failed" },
    { "field": "cost_usd", "operator": "gte", "value": 0.05 }
  ],
  "freeText": "gateway timeout",
  "sort": [{ "field": "cost_usd", "direction": "desc" }]
}
```

Do not send both canonical query text and structured filters in one request.

### Aggregation request

```json theme={null}
{
  "query": "status = failed AND environment = production",
  "groupBy": ["model", "failure_category"],
  "metrics": ["count", "sum_cost", "avg_duration", "p95_latency"]
}
```

### Saved view request

```json theme={null}
{
  "name": "Production tool failures",
  "scope": "project",
  "query": "status = failed AND tool_error exists",
  "columns": ["created", "trace_name", "status", "model", "failure_category", "provenance"],
  "pinnedColumns": ["trace_name"],
  "sort": [{ "field": "created", "direction": "desc" }],
  "isDefault": false
}
```

### Bulk action request

```json theme={null}
{
  "traceIds": [1042, 1048, 1071],
  "datasetId": "c55e41d2-e234-45aa-8dd9-2ea901ad85ff",
  "idempotencyKey": "checkout-timeouts-to-dataset-2026-07-13"
}
```

## Error and recovery states

| Code or state          | Meaning                                                                             | Recovery                                                                |
| ---------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `INVALID_QUERY`        | Syntax or value type is invalid                                                     | Correct the highlighted clause and rerun                                |
| `INVALID_FIELD`        | Field is not in the allowlist                                                       | Choose a supported field                                                |
| `INVALID_OPERATOR`     | Operator is incompatible with the field                                             | Choose an operator from the field type                                  |
| `QUERY_TOO_COMPLEX`    | Query exceeds a contract bound or aggregation exceeds its 15-second database budget | Narrow and split the investigation                                      |
| `INVALID_CURSOR`       | Cursor belongs to another query, sort, or organization                              | Restart from the first page                                             |
| `FORBIDDEN_RAW`        | Actor lacks explicit raw permission                                                 | Use redacted mode or request authorized access                          |
| `IDEMPOTENCY_CONFLICT` | A key was reused with different input                                               | Reuse the original input or issue a new key                             |
| `EXPORT_TOO_LARGE`     | Serialized output exceeded 5 MiB                                                    | Narrow the query or lower `maxRows`                                     |
| Partial bulk result    | Some selected traces were missing or rejected                                       | Correct the destination or selection and retry failed items             |
| Empty result           | No trace matches the canonical query                                                | Broaden the time range or remove a filter                               |
| Expired payload        | Retention removed semantic payloads                                                 | Investigate metadata, costs, scores, and evidence that remain available |