Traces and Remediation

Every proxied request produces a turn record, grouped under a session. Turns carry the model and tool runs, token counts, latency, and the policy and intent decisions.

What a turn records

Field	Description
`trace_id`	Identifier for this turn
`session_id`	The session this turn belongs to
`turn_number`	Position within the session
`proxy_id` / `org_id`	Proxy and organization
`provider`	Resolved upstream provider
`model`	Model the runtime called
`request_type`	`chat_completion`, `chat_completion_stream`, `responses`, or `responses_stream`
`status`	`allowed`, `blocked`, `escalated`, or `error`
`tokens_in` / `tokens_out`	Prompt and completion tokens
`latency_ms`	Total latency
`ttft_ms`	Time to first token (streaming)
`policy_decision` / `policy_rule`	Final policy action and the rule that fired
`intent_score` / `intent_action`	Semantic score and action
`custom_properties`	Key–value pairs from `X-Xenovia-Property-*` headers

Inside a turn, each unit of work is a run: the model call, plus policy, intent, and runtime-executed tool runs. Client-executed tool calls appear in the turn’s output.tool_calls and, once returned, in the next turn’s tool_results.

Enriching a turn

Attach these headers to any proxied request:

client = OpenAI(
    api_key=os.environ["XENOVIA_API_KEY"],
    base_url=f"https://runtime.xenovia.io/{os.environ['XENOVIA_PROXY_ID']}/v1",
    default_headers={
        # Group related calls under one session (a valid UUID)
        "X-Xenovia-Session-Id": "550e8400-e29b-41d4-a716-446655440000",
        # Tag the turn with business context
        "X-Xenovia-Property-user-tier": "enterprise",
        "X-Xenovia-Property-feature": "document-summary",
    }
)

Custom property rules:

At most 20 properties per request; extras are dropped silently.
Property names are lowercased; keep them to 64 characters or fewer.
Values are truncated to 512 bytes.
Names beginning policy_ are reserved and dropped.
A property that breaks a rule is skipped without an error, so confirm important tags appear on the trace.

For cross-request linkage, X-Xenovia-Parent-Trace-Id sets a parent run and X-Xenovia-Trace-Flow-Id groups turns into a flow.

X-Xenovia-Session-Path is not currently read by the runtime. Use X-Xenovia-Session-Id for grouping and X-Xenovia-Property-* for filtering.

Response headers

Every response includes:

Header	Value
`X-Xenovia-Session-Id`	Resolved session UUID
`X-Xenovia-Trace-Id`	Per-request trace UUID

Use X-Xenovia-Trace-Id to find a specific call in the platform. For a malformed X-Xenovia-Session-Id, read the echoed response header to confirm which session the runtime actually used.

Investigating

Notice

Watch the Sessions and Alerts views for a rise in blocks, a drop in intent scores, or a spike in escalations. Configure alert rules to be told rather than to poll.

Drill in

Open a session and read its turns. Each turn carries the messages, tools, model, tokens, decision, and custom properties, so the cause is visible without stitching logs together.

Adjust

Update the Rego policy, change the intent configuration, or revoke a proxy key. Configuration changes reach the runtime within about five minutes.

Confirm

Send the request again and check the new turn. Historical turns are immutable, so earlier decisions remain as evidence after a change.

Escalations surface here and in Alerts as a signal; there is no approve/deny queue to action. Respond by adjusting the policy or intent that raised them.

Querying traces programmatically

The management API exposes sessions, turns, aggregate stats, and multi-proxy workflows. The GET /api/v1/traces endpoint filters by proxy, session, decision, provider, and time range, and by any custom property as cp_<key>=<value>.

Start Here

Integrations

Platform

Traces and Remediation

What a turn records

Enriching a turn

Response headers

Investigating

Querying traces programmatically

​What a turn records

​Enriching a turn

​Response headers

​Investigating

​Querying traces programmatically

What a turn records

Enriching a turn

Response headers

Investigating

Querying traces programmatically