Skip to main content

CLI

verdictan events

Use verdictan events to read the governance events that gateways record, such as the verdict for each request. Use tail to look at recent events. Use export to save all events since a start time as CSV or JSON.

Before you start​

  • A CLI credential: VERDICTAN_API_TOKEN, or a session from verdictan auth login.
  • For tail, the events:read permission. For export, the events:export permission.
  • The region that holds your events. Each command reads one region: the region of the profile, or the value of --region.

The API returns only the events that you can read. With an API token, the results contain only events that belong to teams that the token can read. Events that have no team are visible only to an organization owner or admin who uses a user session, not an API token.

Examine recent requests​

Send a request through your gateway. Then read the events from the last five minutes:

verdictan events tail --since 5m --json

Result: the API response has an events array, newest first. Each event has a verdict, a reason_code, an event_type, and a timestamp. An empty array shows that the query found no events. It does not show that the request failed. Event delivery can be slow. If the array stays empty, make sure that the organization, the region, and the time window are correct.

To follow one request from its event to the policy decision, see Investigate a blocked request.

verdictan events tail​

verdictan events tail sends one query to GET /v1/events and prints one page of events.

Usage​

verdictan events tail --since <duration|rfc3339> [OPTIONS]

The CLI does not make --since mandatory, but the API does. Without --since, the API rejects the query with HTTP 422.

Options​

FlagDescription
--since <duration|rfc3339>Start of the query window. Use an RFC 3339 timestamp, or an integer followed by m, h, d, or w, such as 10m or 7d.
--limit <n>Number of events in one page, from 1 to 100. The default is 100.
--cursor <cursor>Read the next page. Use the next_cursor value from the previous response.
--event-type <type>Return only events of one type, such as decision.
--gateway-id <id>Return only events from one gateway.
--verdict <verdict>Return events with a supported verdict, such as block or blocked.
--followRead the selected window, then poll for new events. Read all pages in each poll.
--follow-interval-secs <n>Seconds between requests with --follow. The default is 5.
--jsonPrint JSON.
--config <path>, --api-url <url>, --profile <name>, --region <region>Standard connection and profile overrides.

The CLI maps allowed, blocked, denied, redacted, rewritten, escalated, and rate_limited to their stored verdicts. The match ignores case. An unknown value stops the command and lists the accepted values. You can also use these stored values:

VerdictVerdictVerdict
allowblockdeny
redactrewriteescalate
approval_requiredpendingrate_limit

The event types gateway.request.outcome and gateway.provider.attempt can also have the verdict error.

Examples​

# Events from the last hour, as JSON
verdictan events tail --since 1h --json

# Blocked events from the last day
verdictan events tail --since 1d --verdict block --json

# Events from one gateway
GATEWAY_ID="replace-with-your-gateway-id"
verdictan events tail --since 30m --gateway-id "$GATEWAY_ID" --json

Copy the gateway ID from Gateways in the Console.

To read more than one page, run the command again with the same --since value and the cursor from the last response:

verdictan events tail --since 1d --cursor "replace-with-next_cursor" --json

Output​

With --json, the command prints the API response:

FieldDescription
eventsThe events on this page, newest first.
next_cursorThe cursor for the next page of older events. It is null on the last page.

Each event has event_id, event_type, request_id, timestamp, verdict, reason_code, config_version, and event_attribution. When the data is available, an event also has trace_id, config_id, environment, details, metadata, prompt_redacted, prompt_hash, and event_cost_attribution.

Without --json, the command prints one line for each event:

  <time> <event-type> <verdict> model=<model> policy=<policy>

The text line reads the event_time, model, and policy_name fields. The event records from GET /v1/events do not have these fields, so the time, model, and policy show -. Use --json to see the timestamp and the reason code. If the page has no events, text mode prints No events found.

verdictan events export​

verdictan events export sends GET /v1/events/export and writes the response bytes to standard output.

Usage​

verdictan events export --since <duration|rfc3339> --format <csv|json> [OPTIONS]

Options​

FlagDescription
--since <duration|rfc3339>Mandatory start of the export window. Use an RFC 3339 timestamp, or an integer followed by m, h, d, or w.
--format <csv|json>Mandatory export format.
--config <path>, --api-url <url>, --profile <name>, --region <region>Standard connection and profile overrides.

The export contains all events from the start time to now, oldest first. It has no page limit and no filters. The API applies the same team limits as tail.

FormatContent
csvA header row, then one row for each event with the columns event_id, timestamp, event_type, request_id, verdict, reason_code, and config_version.
jsonOne object with an events array. Each event has the same fields as in tail --json.

Examples​

# Export the last 7 days as CSV
verdictan events export --since 7d --format csv > events-7d.csv

# Export the events since a fixed time as JSON
verdictan events export --since 2026-09-01T00:00:00Z --format json > events-september.json

To verify the CSV file, count its rows. The first line is the header:

wc -l events-7d.csv

Limits and failure behavior​

  • tail --follow --since 5m runs until you stop it with Ctrl+C or a request fails. Every request includes since. The CLI reads older pages before it polls for new events.
  • Follow mode uses the newest event timestamp as the next lower bound. It suppresses duplicate event IDs at that timestamp. The query can miss events that arrive with an older timestamp. Use a wider one-shot query to find them.
  • Follow mode with --json prints each new event as a JSON object. One-shot mode prints the page object.
  • tail returns at most 100 events on one page. A --limit value outside 1 to 100 causes HTTP 422.
  • export is one synchronous request that returns all matching events. For a large window, use verdictan export-jobs to prepare the file in the background.
  • The commands do not accept a token on the command line. The CLI rejects --api-token before it parses the command. Use VERDICTAN_API_TOKEN or a stored profile.
  • Each command reads one region. Run it again with --region for each region that you operate.

Troubleshooting​

SymptomCauseFix
missing api token (set VERDICTAN_API_TOKEN or run `verdictan auth login`)No credential is available.Set VERDICTAN_API_TOKEN, or run verdictan auth login.
tail stops with api validation failed (422)--since is missing or not valid, or --limit is outside 1 to 100.Add a valid --since value. Keep --limit from 1 to 100.
tail stops with api authorization failed (403)The credential does not have events:read.Ask an administrator for a role with events:read.
export stops with authorization failed for events export (HTTP 403)The credential does not have events:export.Ask an administrator for a role with events:export.
export stops with validation error for events export (HTTP 422)The --since value is not valid.Use an RFC 3339 timestamp or a value such as 24h.
--verdict blocked returns no eventsStored verdicts use the short form.Use --verdict block.
The results do not contain events that you expectThe events are in a different region, have no team, or belong to a team that you cannot read.Check --region, and check your team membership and role.

Next steps​