Skip to main content

Debug AI Requests

A connected gateway can send Event evidence for Chat Completions and Responses requests. Event delivery must be available. History keeps context only when you configure capture. Use the CLI or Events API for delivered request results. Use the console for captured session context, audit sequence, and review work.

Verdictan does not guarantee evidence for each request. You can disable History. History delivery uses fire-and-forget operation. A standalone gateway can have no control-plane event destination. Messages and WebSocket traffic use different evidence paths.

If a record is missing, examine capture, connectivity, and request-family support. Do not conclude that the request did not occur.

Before you start​

  • Select an authenticated CLI profile for the applicable region. Alternatively, give a control-plane token with events:read.
  • Do not use an application request token as a replacement.
  • Keep the client response, UTC time period, request ID, gateway or agent, model, and environment.
  • Make sure that the application used the specified gateway and a documented request family.
  • Use History, Trail, and Inbox only when a record is available.
  • Make sure that your role can read the applicable surface.

Select the correct surface​

TaskBest surface
Delivered runtime Event while reproducing an issueverdictan events tail
Delivered runtime result for one requestverdictan events tail or GET /v1/events with the necessary since parameter
Stored prompt, response, or session contextHistory, only when you enable capture
Audit chronology or exportable evidenceTrail
Human-review items created by the requestInbox
Runtime inventory and healthGateways

Start with delivered Events during reproduction​

Follow newly delivered Events:

verdictan events tail --follow

Recent decision events as JSON:

verdictan events tail --since 10m --event-type decision --limit 20 --json

Only blocked decisions:

verdictan events tail --follow --event-type decision --verdict blocked

Limit investigation to one gateway:

verdictan events tail --since 30m --gateway-id gw_123 --json

The command polls the authenticated Events API. A matching request ID shows that the gateway delivered Event evidence to the control plane. The command does not read local gateway process output.

Add History only when captured detail is available​

After you identify the request Event, use History only when you enable capture. Use it to answer these questions:

  • What prompt, response, or session context did History keep?
  • How does the captured session compare with nearby captured requests?
  • Did retained content change after a rollout?

Use the Event and request ID for the result, policy evidence, config version, provider, and model. A missing History record does not prove that the request did not occur.

Use Trail when chronology or export is necessary​

Use Trail to:

  • Examine the audit sequence of related actions.
  • Export evidence for incident response or compliance review.
  • Find proof of follow-up activity after the initial request.

Use Inbox when the request triggered human review​

If the request has a review task, open Inbox. Examine the linked review item. Resolve it only after you understand the request context.

Frequent request problems​

A policy blocks a request unexpectedly​

  1. Run verdictan events tail --follow --event-type decision --verdict blocked.
  2. Reproduce the issue.
  3. Match the request ID.
  4. Review the Event policy results and config version.
  5. If you enable capture and session context is necessary, open the matching request in History.
  6. Compare the request with the last rollout in Configurations.

A request is slow​

  1. Verify the active problem with verdictan events tail --since 10m --limit 20 --json.
  2. Examine gateway and provider health from the runtime diagnostics.
  3. Open Gateways to verify that the specified runtime is healthy.
  4. Compare nearby Events and runtime metrics.
  5. Identify if one request or the full system has the problem.
  6. Add captured History context only when you enable capture and this context.

A request triggered human review​

  1. Open the related Inbox item.
  2. Keep its request ID.
  3. Query the matching Event with verdictan events tail --since <window> --json or GET /v1/events?since=<window>.
  4. Add History only when you enable capture and the session context is necessary.
  5. Resolve the review item only after you understand the request and rollout context.

Best practices​

PracticeWhy
Use verdictan events tail --follow during reproduction.This shows newly delivered Events from the authenticated Events API.
Limit results with --verdict, --event-type, or --gateway-id.This keeps the live output clear.
Compare request Events before and after rollout.This shows the difference between config problems and one-time incidents.
Use History only for captured context.A missing session does not prove that no request occurred.
Use Trail for evidence export.This connects audit exports to customer workflows.

Next steps​