Skip to main content

verdictan escalation

Use verdictan escalation to operate the control-plane review queue from a terminal or an automation that acts for an authenticated reviewer. The commands do not create escalations or configure reviewer routing.

Prerequisites​

Make sure that you have these prerequisites:

  • An escalation in the organization and region you will query.
  • VERDICTAN_API_URL and VERDICTAN_API_TOKEN, a configured profile, or an interactive CLI login.
  • escalations:read to list or examine records.
  • escalations:claim to claim or unclaim records.
  • escalations:resolve to record a last decision.
  • An identity-bound user credential for claim, unclaim, and resolve. The API derives the actor from its authenticated request context. A machine credential without a user_id cannot act as a human reviewer.

Before you change queue state, verify the active identity:

verdictan auth whoami --json

For mutations, make sure that the response includes the specified organization and a non-null user_id. Run verdictan regions current to examine the resolved region and API endpoint. If the defaults are not the correct review boundary, use --profile and --region on each command.

Understand the status lifecycle​

StatusMeaningAvailable next action
queuedWaiting for a reviewer, including an item returned by unclaimClaim
claimedOwned by one reviewerResolve or unclaim
resolvedContains the last resolutionRead only

The API and CLI do not accept open as an escalation status.

List a bounded queue​

You must specify --since. The command accepts an RFC 3339 timestamp or a relative duration ending in m, h, d, or w.

verdictan escalation list --since 24h
verdictan escalation list --since 7d --status queued --agent-id agent_abc123
verdictan escalation list --since 30d --status resolved --limit 100 --json

--status accepts only queued, claimed, or resolved. --limit accepts 1–100 and defaults to 25.

For pagination, use --json. Copy the response's non-null next_cursor. Send it with the same time window and filters:

verdictan escalation list \
  --since 30d \
  --status queued \
  --cursor "$NEXT_CURSOR" \
  --limit 100 \
  --json

An empty result means that no records matched the selected organization, region, time window, and filters. An escalation can be in a different region. Its time can also be before or after the selected window.

Examine one escalation​

Start with the record itself:

verdictan escalation get --escalation-id esc_abc123
verdictan escalation get --escalation-id esc_abc123 --json

Examine the request ID, cause code, status, configuration version, creation time, and active claimant. To understand why the request is in review, get linked event context from the API:

verdictan escalation get \
  --escalation-id esc_abc123 \
  --include-context \
  --json

The API can return no context or redact context because of the initial capture settings and data availability. Use the returned escalation and governance Events as the authoritative queue evidence. Do not infer a clean request from missing content.

Claim work​

To start the review, claim the item:

verdictan escalation claim --escalation-id esc_abc123
verdictan escalation get --escalation-id esc_abc123 --json

The API attributes the mutation to the authenticated user_id. The CLI does not accept or send a caller-selected actor identity. A claim operation is idempotent for that authenticated reviewer. The API returns HTTP 409 if a different reviewer owns the item. It also returns HTTP 409 if the item is resolved.

Return work to the queue​

When you no longer own a record, unclaim it:

verdictan escalation unclaim --escalation-id esc_abc123
verdictan escalation get --escalation-id esc_abc123 --json

When an unclaim succeeds, it changes claimed to queued. It also clears the claimant and claim time. Claimants can release their own records. Users with assignment management authority can release a different reviewer's claim. The API returns HTTP 409 for an unclaimed or resolved item. It does not silently change the item.

Resolve a claimed escalation​

Only the active claim owner can resolve it. Select one supported resolution:

ResolutionUse when
allowRecord the reviewer decision as allowed
blockRecord the reviewer decision as blocked
rewriteRecord that a rewrite is necessary
redactRecord that redaction is necessary
rejectedRecord that the escalation is rejected

The resolve command updates the review record. It does not replay or change the gateway request that the gateway processed earlier.

Record the decision:

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

The optional --note accepts a maximum of 2,000 bytes. The optional --category accepts:

  • false_positive
  • true_positive_approved
  • true_positive_blocked
  • needs_policy_update
  • needs_rewrite
  • duplicate
  • other

Resolution and category are two fields. For example, block identifies the last action. The true_positive_blocked value classifies the applicable cause.

Before you mark the workflow as complete, read the record again:

verdictan escalation get --escalation-id esc_abc123 --json

Verify status: resolved, the selected resolution, and the note or category that you supplied.

Safe troubleshooting​

  • Missing API token: run verdictan auth login. Alternatively, set VERDICTAN_API_TOKEN. Then verify the identity with verdictan auth whoami --json.
  • No user_id in whoami or 403 auth.user_required: use an identity-bound user credential. A caller-selected actor ID does not authenticate the user.
  • Permission denied: request only the permission necessary for the operation: escalations:read, escalations:claim, or escalations:resolve.
  • Validation error while listing: specify --since. Use a supported status. Keep --limit between 1 and 100.
  • Validation error while resolving: use a supported resolution and category. Keep the note at or below the size limit.
  • HTTP 409: a different reviewer changed the item, no reviewer owns it, or it is resolved. Fetch the escalation again. Use the returned state to select the next action. Do not retry a mutation without a review.
  • Unexpected empty queue or not found: verify the organization, profile, region, time window, agent filter, and escalation ID.

For automation, use --json. Preserve the same filters across cursor pages. HTTP 409 responses to claims are concurrency signals. Start a new read for each HTTP 409 response.

Next steps​