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

# Segments

> Your logged traffic, auto-grouped by system-prompt family — every application surface separable with zero setup, retroactively.

Most workspaces serve more than one thing through one key: a support bot, an
extraction pipeline, an internal tool. Every measurement downstream (logs,
datasets, [comparisons](/reference/evals), [judge](/judges/calibration)
populations) is only meaningful **per surface**; a blended average measures a
workload nobody actually runs.

Tags solve this when you remembered to send them. **Segments** solve it when
you didn't: Omnia auto-groups your logged traffic by **system-prompt family**:
every request whose system prompt came from the same template lands in the
same segment, with zero setup on your side.

## How a segment is detected

A segment is derived from the system prompt itself:

1. **Normalized**: interpolated values that vary per request (UUIDs, emails,
   timestamps, numbers) are scrubbed, so `"You are a support agent. Today is
   2026-08-03. Customer id 4821…"` and the same prompt on any other day
   normalize identically.
2. **Prefixed**: the first 512 characters of the normalized prompt form the
   stable identity. Templates diverge early; suffixes (retrieved context,
   conversation history injected into the prompt) don't fragment the family.
3. **Hashed**: the identity is stored as a hash. A segment value is 16 hex
   characters of opaque, stable id, never your prompt text. Traffic with no
   system prompt at all lands in the reserved `none` segment.

The result is **interpolation-proof**: a prompt template that stamps in dates,
ids, or per-customer context still resolves to one segment. And because
detection runs over what's already logged, it's **retroactive**: the traffic
you captured last month is already segmented today.

Each logged exchange also carries `segment_exact`, the hash of the exact
system prompt within the family, for the rare case where one interpolated
variant matters.

## Where segments show up

* **Logs**: a **Segment** filter on the Logs page (and `?segment=` on
  [`GET /v1/logs`](/api-reference/introduction) and the JSONL export), so one
  surface's traffic is one filter away.
* **Comparisons**: the compare flow scopes to a segment
  (`sample_filters.segment` on `POST /v1/evals`), so a bake-off samples one
  application surface instead of your blended traffic.
* **Datasets**: curation can be scoped to a segment
  (`filters.segment` on `POST /v1/datasets/from_logs`), and the dataset keeps
  that provenance: you know which surface it was cut from.
* **Judge populations**: a judge can bind its population to a segment
  (`population_family` on the criteria API), so it scores, and is
  [calibrated](/judges/calibration) against, exactly the traffic it
  will judge. Changing that binding voids the calibration, like any
  population change.

## Segments and tags compose

[`X-Omnia-Tag`](/reference/observability#request-labels-tags-and-trace-ids)
remains the deliberate override: a tag says what *you* declare a request to
be; a segment says what the traffic *is*. They compose: filter by both, and
you get the intersection.

Use tags when one prompt template serves several purposes you want measured
separately (the same assistant behind two customer tiers), or when you want a
name that survives a prompt rewrite. Use segments for everything you never
tagged, which, in practice, is most traffic.

```bash theme={null}
# Slice logged traffic to one auto-detected surface
curl "https://gateway.omnia-voice.com/v1/logs?segment=9f3a8c2e41d07b56&limit=25" \
  -H "Authorization: Bearer $OMNIA_API_KEY"

# Run a comparison sampled from that surface only
curl -X POST https://gateway.omnia-voice.com/v1/evals \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "checkout assistant: 30B bake-off",
    "rubric": "...",
    "baseline_model": "Qwen/Qwen3-32B",
    "candidate_models": ["Qwen/Qwen3-30B-A3B-Instruct-2507"],
    "sample_count": 100,
    "sample_filters": { "segment": "9f3a8c2e41d07b56" }
  }'
```

Segment values come from your own logs: read any row's `segment` field, or
pick one from the Logs page's Segment filter.

<Note>
  Segments exist only where [request logging](/reference/request-logging) is on:
  they're derived from logged system prompts, so nothing is segmented while
  nothing is captured.
</Note>