verdictan escalation

Use verdictan escalation to review requests that a policy sent to a human reviewer. You find an item in the queue, claim it so that other reviewers know that you own it, and then record your decision. For the same workflow in the Console, see Resolve an escalation.

The commands do not create escalations and do not configure reviewer routing. A policy control with an escalation verdict creates each record. See Human Oversight for that configuration.

Before you start

• A CLI credential: VERDICTAN_API_TOKEN, or a session from verdictan auth login.

• These permissions:

  Subcommand	Permission
  list, get	escalations:read
  claim, unclaim	escalations:claim
  resolve	escalations:resolve

• For claim, unclaim, and resolve, a credential that identifies a user. The API records the authenticated user as the reviewer. A credential without a user, such as a machine token, gets HTTP 403 with auth.user_required.

To check your credential, run verdictan auth whoami --json. The output must contain a user_id field.

Find an item to review

1. List the queued items from the last day:

   verdictan escalation list --since 24h --status queued

2. Copy an escalation ID. Read the record and the event that caused it:

   ESCALATION_ID="replace-with-an-id-from-the-queue"
   verdictan escalation get --escalation-id "$ESCALATION_ID" --include-context --json

3. Examine reason_code, request_id, status, and event_context. The captured context can be missing or redacted. Missing content does not show that the request was safe.

An escalation has one of three statuses:

Status	Meaning	Next action
queued	No reviewer owns the item.	claim
claimed	One reviewer owns the item.	resolve, or unclaim to return it to the queue
resolved	A reviewer recorded a decision.	None. The record is read-only.

verdictan escalation list

verdictan escalation list sends GET /v1/escalations and prints one page of escalations, newest first.

Usage

verdictan escalation list --since <duration|rfc3339> [OPTIONS]

Options

Flag	Description
--since <duration|rfc3339>	Mandatory start of the window. The API compares it with the creation time of the escalation. Use an RFC 3339 timestamp, or an integer followed by m, h, d, or w.
--status <queued|claimed|resolved>	Return only escalations with this status.
--agent-id <id>	Return only escalations for one agent.
--limit <n>	Number of escalations on one page, from 1 to 100. The default is 25.
--cursor <cursor>	Read the next page. Use the next_cursor value from the previous JSON response.
--json	Print the API response as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Standard connection and profile overrides.

Examples

# All escalations from the last 24 hours
verdictan escalation list --since 24h

# Queued items for one agent in the last 7 days
verdictan escalation list --since 7d --status queued --agent-id "replace-with-agent-id"

# The next page, with the same window and filters
verdictan escalation list --since 7d --status queued --limit 100 --cursor "$NEXT_CURSOR" --json

In text mode, the command prints one line for each escalation: <escalation-id> <status> <reason-code> <created-at>. If the page is empty, it prints no escalations.

With --json, the response has these fields:

Field	Description
escalations	The escalations on this page.
next_cursor	The cursor for the next page of older escalations. It is null on the last page.
total	The number of escalations that match the window and filters.

To read the next page, send the cursor with the same --since value and the same filters.

verdictan escalation get

verdictan escalation get sends GET /v1/escalations/<id> and prints one escalation.

Usage

verdictan escalation get --escalation-id <id> [--include-context] [--json]

Options

Flag	Description
--escalation-id <id>	Mandatory escalation ID.
--include-context	Add the triggering event and its evidence data. The CLI sends include=context.
--json	Print the API response as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Standard connection and profile overrides.

Examples

# The record: ID, status, reason code, creation time, claimant, and resolution
verdictan escalation get --escalation-id "$ESCALATION_ID"

# The record with the triggering event context
verdictan escalation get --escalation-id "$ESCALATION_ID" --include-context --json

The escalation record has these fields: escalation_id, request_id, org_id, project_id, team_id, agent_id, config_version, reason_code, status, created_at, claimed_at, claimed_by, resolved_at, resolution, and resolution_note. When they have a value, it also has resolution_category and escalation_routing_hint.

Without --include-context, the JSON response puts the record in an escalation object. With --include-context, the record fields are at the top level, and the response can add these fields:

Field	Description
event_context	The governance event for the same request: event_id, event_type, verdict, reason_code, config_version, timestamp, and, when stored, trace_id, details, metadata, prompt_redacted, and prompt_hash.
trace_summary	A summary of the trace. The API adds it only when the event has a trace ID and you have events:read.
evidence_exports	Integrity records of export jobs that can contain the event.

The capture settings of your deployment control what the context contains. Use the escalation record and the governance events as the review evidence.

verdictan escalation claim

verdictan escalation claim sends POST /v1/escalations/<id>/claim. It assigns a queued escalation to you.

Usage

verdictan escalation claim --escalation-id <id> [--json]

Options

Flag	Description
--escalation-id <id>	Mandatory escalation ID.
--json	Print the updated escalation as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Standard connection and profile overrides.

Examples

verdictan escalation claim --escalation-id "$ESCALATION_ID"
verdictan escalation get --escalation-id "$ESCALATION_ID"

Result: the command prints claimed escalation <id>. get shows the status claimed and your user ID in claimed_by.

The API sets claimed_by to the authenticated user. You cannot claim an item for a different user. If you claim an item that you own already, the API returns the current record and makes no change.

verdictan escalation unclaim

verdictan escalation unclaim sends POST /v1/escalations/<id>/unclaim. It returns a claimed escalation to the queue.

Usage

verdictan escalation unclaim --escalation-id <id> [--json]

Options

Flag	Description
--escalation-id <id>	Mandatory escalation ID.
--json	Print the updated escalation as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Standard connection and profile overrides.

Examples

verdictan escalation unclaim --escalation-id "$ESCALATION_ID"

Result: the command prints unclaimed escalation <id>. The status changes from claimed to queued, and the API clears claimed_by and claimed_at.

The claimant can release the item. A user with the teams:manage or users:manage permission can also release a claim that belongs to a different reviewer.

verdictan escalation resolve

verdictan escalation resolve sends POST /v1/escalations/<id>/resolve. It records the decision for an escalation that you claimed. Only the current claimant can resolve the item.

Usage

verdictan escalation resolve --escalation-id <id> --resolution <resolution> [--category <category>] [--note <text>] [--json]

Options

Flag	Description
--escalation-id <id>	Mandatory escalation ID.
--resolution <resolution>	Mandatory decision: allow, block, rewrite, redact, or rejected.
--category <category>	Classification of the cause: false_positive, true_positive_approved, true_positive_blocked, needs_policy_update, needs_rewrite, duplicate, or other.
--note <text>	A note about the decision. The API accepts at most 2000 bytes.
--json	Print the updated escalation as JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>	Standard connection and profile overrides.

The resolution and the category are two different fields. --resolution records the decision. --category records why the policy escalated the request. For example, block with true_positive_blocked records a correct escalation that you blocked.

Examples

verdictan escalation resolve \
  --escalation-id "$ESCALATION_ID" \
  --resolution allow \
  --category false_positive \
  --note "Reviewed against the active policy"

To verify the result, read the record again. Then find the governance event that the API writes for the resolution:

verdictan escalation get --escalation-id "$ESCALATION_ID" --json
verdictan events tail --since 1h --event-type escalation.resolved --json

The record shows status resolved, with resolution, resolution_category, resolution_note, and resolved_at. The escalation.resolved event has the same request ID, and its metadata contains the escalation ID, your user ID, and the decision.

The command records the review only. It does not send the original request again and does not change the response that the gateway returned earlier.

Limits and failure behavior

• list needs --since. The CLI accepts only queued, claimed, or resolved for --status. A --limit outside 1 to 100 gives HTTP 422.
• get, claim, unclaim, and resolve return HTTP 404 for an ID that is not in your organization. The CLI prints api request failed with status 404.
• An escalation that belongs to a team needs a permission for that team. Without it, the API returns HTTP 403 with auth.insufficient_permissions.
• resolve rejects a note longer than 2000 bytes with HTTP 422.
• Each command uses the region that the profile or --region selects. An escalation from a different region is not found.

Troubleshooting

The API returns HTTP 409 when the state of the escalation does not allow the change. The CLI prints api conflict (409). Read the escalation again before you retry, and select the next action from its current status.

Symptom	Cause	Fix
api conflict (409) from claim	A different reviewer claimed the item (conflict.already_claimed), or it is resolved (conflict.already_resolved).	Run get. Select a different item.
api conflict (409) from unclaim or resolve	The item is not claimed (conflict.not_claimed), a different reviewer owns it (conflict.claimed_by_other), or it is resolved.	Run get. Claim the item first, or ask its owner to release it.
api conflict (409) after a retry	The state changed during the request (conflict.stale_state).	Run get, then select the next action.
api authorization failed (403) from claim, unclaim, or resolve	The credential has no user (auth.user_required), or it does not have the permission.	Sign in with verdictan auth login as a reviewer, and check the role.
api validation failed (422) from list	--since or --limit is not valid.	Use a value such as 24h, and a limit from 1 to 100.
no escalations	No item matches the region, the window, and the filters.	Check --region, use a longer --since window, and remove filters.

Next steps

• Resolve an Escalation: do the same review in the Console Inbox.
• Human Oversight: configure the control that creates escalations.
• Reviewing Alerts and Evidence: examine the evidence for an escalated request.
• Permissions Reference: grant the escalations:* permissions.