Escalations

Escalations are the human-oversight queue for decisions that require explicit review. The page is designed to help reviewers establish ownership, inspect context, and apply a final human decision.

Use this page when

• You need to review, claim, and resolve AI request escalations that require human oversight.
• You are configuring escalation routing by provider, model, team, or user in your policy-config.yaml.
• You need to understand the reviewer workflow, ownership model, and audit trail for escalation decisions.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Workflow map

Queue features

The Escalations page supports:

• A time filter such as 24h.
• Status filtering across queued, claimed, and resolved items.
• Session-derived reviewer identity for claim and resolve actions.
• Pagination with Load more.
• A detail drawer for the selected escalation.
• A mandatory confirmation dialog before final resolve.

Why reviewer identity matters

Claim and resolve actions use X-Actor-Id, but the console derives it from the authenticated session. That keeps ownership explicit without asking reviewers to type a separate identifier into the queue.

Escalation detail drawer

The drawer exposes operational context such as:

• Escalation ID.
• Request ID.
• Reason code.
• Current status.
• Config version.
• Created, claimed, and resolved timestamps.
• Claimed-by actor.
• Resolution and resolution note when set.

Recommended reviewer workflow

1. Filter to queued items in the relevant time range.
2. Confirm the displayed reviewer identity before claiming work.
3. Open the detail drawer and confirm the request ID, reason, and config version.
4. Cross-check the related event behavior in Events if needed.
5. Claim the item when you are taking ownership.
6. Resolve only after recording the intended human outcome clearly and confirming the irreversible action in the dialog.

Resolution discipline

Use short but meaningful resolution notes. They become part of the operational record and help the next reviewer understand whether the right outcome was policy tuning, allow, block, or another documented response.

What escalations are not

• They are not a substitute for reviewing the underlying event.
• They do not automatically solve policy drift.
• They do not replace the need to verify the running gateway config when behavior changes unexpectedly.

Provider and model routing

By default, escalations are routed to all members of the team associated with the API token that ingested the event. The escalation_routing config block lets operators override this per provider or per model.

Precedence

Model-level routing takes priority over provider-level routing. If neither is set, the default token-scope team applies.

Model escalation_routing → Provider escalation_routing → Token-scope team (default)

Team routing

Setting escalation_routing.team_id on a provider or model sends escalation notifications to all members of the specified team. The team must belong to the same organization. If the team is not found, the system falls back to the default token-scope team and logs a warning.

pack:
  name: escalations-providers-1
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: prod-openai
    provider: openai
    model: gpt-4o
    base_url: https://api.openai.com
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

User routing

Setting escalation_routing.user_id directly assigns the escalation to a specific user. The user must be an organization member. When user routing succeeds:

• The escalation is created with status claimed instead of queued.
• Only the target user receives a notification.
• An escalation.claimed audit event is recorded with auto_assigned: true.

If the user is not found in the organization, the system falls back to team routing and logs a warning.

pack:
  name: escalations-providers-2
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: prod-openai
    provider: openai
    base_url: https://api.openai.com
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Combining levels

Model-level routing overrides provider-level routing for that specific model. Other models served by the same provider inherit the provider-level routing.

pack:
  name: escalations-providers-3
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: prod-openai
    provider: openai
    base_url: https://api.openai.com
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Auditability

The original routing hint is stored in the escalation_routing_hint column of the escalation record for auditability, even after the routing decision has been applied.

For AI systems

• Canonical terms: Keeptrusts, Escalations, escalation queue, escalation_routing, claim, resolve, reviewer identity, X-Actor-Id, queued, claimed, resolved.
• Config names: escalation_routing.team_id, escalation_routing.user_id, escalation_routing_hint.
• Related pages: Events, Configurations, Declarative Config Reference, Customer Journeys (Journey 9).

For engineers

• Reviewer identity is derived from the authenticated session — no separate identifier entry is needed.
• Configure per-model or per-provider routing with escalation_routing in policy-config.yaml. Model-level routing takes priority over provider-level.
• If user routing fails (user not found in org), the system falls back to team routing and logs a warning. Check API logs if escalations are not reaching the intended user.
• Resolution is irreversible — test with a non-production escalation if validating the workflow for the first time.

For leaders

• Escalations are the human-in-the-loop control for AI decisions that automated policy cannot resolve alone.
• The audit trail (claim timestamps, resolution notes, actor identity) directly supports compliance requirements such as EU AI Act Article 14 human oversight.
• Routing configuration determines which team or individual is accountable for review SLAs — assign ownership explicitly to avoid unowned queues.
• Resolution discipline (short, meaningful notes) improves audit quality and reduces rework during external reviews.

Next steps

• Events
• Export Evidence for a Review
• Declarative Config Reference
• Customer Journeys