verdictan history

Use verdictan history to find, read, and export the conversations that the gateway captured in History. History contains only the traffic that was captured. It cannot restore message content that was not captured.

Before you start

• Set VERDICTAN_API_TOKEN, or sign in with verdictan auth login.
• To read sessions across the organization, you need the history:read permission. Without it, you can read only the sessions where your user or one of your teams is a conversation member. search always needs the organization-level history:read permission.
• Session, team, and agent IDs are UUIDs. The API rejects other values with HTTP 422.

Each subcommand accepts --config <path>, --api-url <url>, --profile <name> (default default), and --region <region>. All subcommands except export accept --json. The option tables below list only the command-specific flags.

Choose a command for your task:

Subcommand	Purpose
list-sessions, get-session, export	Find a session, read its entries, or save a complete copy.
search	Search captured content and session titles.
stats	Count matching sessions and their entries across all pages.
learn	Ask the API to condense a session.
tag	List, add, or remove session tags.
share	Add a user or team as a session member.
condense	Extract captured text locally, without a model call.
replay	Deprecated. Export a session and send the requests through the gateway yourself.

Find a conversation and read it

1. List the sessions with the most recent activity:

   verdictan history list-sessions --limit 10

   Each line shows the session ID, a scope column, the entry count, and the last activity time.

2. Copy a session ID from the result. Read the session and its entries:

   SESSION_ID="replace-with-a-session-id-from-the-list"
   verdictan history get-session --session-id "$SESSION_ID" --json

   The session object holds the summary. The entries array holds the first 500 entries in request_index order.

3. Export the complete session to a file:

   verdictan history export "$SESSION_ID" --format json --output session.json

   The file can contain prompts and responses. Store it where only authorized readers have access.

4. Verify that the export is complete. The two numbers must match:

   jq '(.entries | length), .session.entry_count' session.json

   export refuses to write the file when it receives fewer entries than entry_count, so a written file always passes this check.

verdictan history list-sessions

verdictan history list-sessions reads GET /v1/history/sessions, newest activity first. It follows the page cursors until it has --limit matching sessions or the results end.

Usage

verdictan history list-sessions [--team-id <id>] [--agent-id <id>] [--since <rfc3339>] [--until <rfc3339>] [--limit <n>] [--json]

Options

Flag	Description
--team-id <id>	Return only sessions for this team. The API filters on the team ID.
--agent-id <id>	Return only sessions for this agent. The API filters on the agent ID.
--since <rfc3339>	Keep sessions with last_activity_at after this time. The API applies this filter.
--until <rfc3339>	Keep only sessions with last_activity_at at or before this time. The CLI applies this filter while it reads the pages.
--limit <n>	Maximum number of sessions to print after the filters. The default is 50. A larger value reads more pages.
--scope <user|team|org>	Deprecated. The CLI prints a warning. Use --team-id or --agent-id to filter.
--tag <name>	Filter the returned sessions by tag in the CLI.

Text output prints one line for each session:

<session_id>	<scope>	entries=<entry_count>	last_activity=<last_activity_at>

The scope column always shows -, because the session record has no scope field. With --json, the command prints {"sessions": [...]}. Each session has fields such as session_id, actor_user_id, actor_team_id, agent_id, started_at, last_activity_at, entry_count, allowed_entry_count, blocked_entry_count, title, last_model, and tags. When no session matches, text output prints no sessions.

Examples

verdictan history list-sessions
verdictan history list-sessions --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --limit 5
verdictan history list-sessions --since 2026-09-01T00:00:00Z --json

verdictan history get-session

verdictan history get-session reads one session from GET /v1/history/sessions/{id}. The response contains the session summary and its first 500 entries.

Usage

verdictan history get-session --session-id <id> [--include-entries] [--json]

Options

Flag	Description
--session-id <id>	Required. The session ID.
--include-entries	Read all entry pages and return a flat .entries array. The default response contains the first 500 entries.

Text output prints session_id, scope, started_at, entry_count, allowed, and blocked. The scope line always shows -. Use --json to read the entries.

If the second request fails, the command prints warning: could not fetch entries: <error> to standard error. The output then keeps the entries from the first response.

Examples

verdictan history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c
verdictan history get-session --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --json

verdictan history export

verdictan history export writes every entry of one session to standard output or a file. Use it when a session has more than 500 entries, or when you need a file you can check.

Usage

verdictan history export <session-id> [--format <markdown|json|txt>] [--output <path>]

Options

Flag	Description
<session-id>	Required. The session ID.
--format <markdown|json|txt>	Output format. The default is markdown.
--output <path>	Write to this file, not to standard output. The command prints exported to <path> to standard error.

The command reads the session, then reads the entries in pages of 500 with limit and offset. It writes nothing until it has all pages. It stops with an error when:

• An entry has no entry_id or no integer request_index.
• An entry_id repeats, or request_index does not increase.
• The pages end before the session entry_count. The message is history entries pagination ended after <n> entries, but the session reports <m>; refusing an incomplete export.

The formats contain:

Format	Content
json	{"session": {...}, "entries": [...]} with the complete entry objects.
markdown	A YAML front matter block with session_id, started_at, entry_count, and tags (when the session has tags), then one ## <role> heading and the text for each entry.
txt	One [<role>]: <text> paragraph for each entry.

In markdown and txt, the role is the role of the last request message, or the entry_kind when there is none. The text is the first response choice message content. When there is none, the text is the last request message content.

Examples

SESSION_ID="7f92ff69-7b29-4f2d-a8bb-766c06e61d3c"

verdictan history export "$SESSION_ID"
verdictan history export "$SESSION_ID" --format json --output session.json
verdictan history export "$SESSION_ID" --format txt --output session.txt

The API has two more export endpoints that the CLI does not call. Both need history:read and return the file in the response:

Endpoint	Selection	Formats	Bound
GET /v1/history/sessions/{id}/export	One session	markdown, json, csv	First 1000 entries
POST /v1/history/sessions/export	At most 50 session IDs	jsonl, csv	First 1000 entries for each session

verdictan history tag

verdictan history tag lists, adds, or removes tags on one session. Changes read the current tags and send the updated list to PATCH /v1/history/sessions/{id}/tags.

Usage

verdictan history tag <session-id> [--tag <name> | --remove <name>] [--json]

Options

Flag	Description
<session-id>	Required. The session ID.
--tag <name>	Add a tag and preserve the other tags.
--remove <name>	Remove a tag and preserve the other tags.

Without --tag and --remove, the command lists the tags from the session. Text and JSON output both work. The API accepts at most 50 tags of at most 100 characters. Changes need history:write for the session. Tag updates replace the list, so concurrent edits can overwrite each other.

Examples

verdictan history tag 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --json

verdictan history search

verdictan history search sends a full-text query to GET /v1/history/search. The search covers entry content and session titles in the organization.

Usage

verdictan history search --query <text> [--entry-kind <kind>] [--agent-id <id>] [--team-id <id>] [--json]

Options

Flag	Description
--query <text>	Required. The search text. The API rejects empty text with 400 search.invalid_query.
--entry-kind <kind>	Return only one entry kind: chat, tool_call, system, system_annotation, or streaming_chunk.
--agent-id <id>	Return only entries for this agent.
--team-id <id>	Return only entries for this team.
--since <rfc3339>	Earliest captured-entry time. The CLI sends it as date_from to server search. Fallback search also uses it.
--until <rfc3339>	Latest captured-entry time. The CLI sends it as date_to to server search. Fallback search also uses it.
--limit <n>	Maximum results. The default is 20. The CLI sends it as size to server search. Fallback search also uses it.

Text output lists the server hits. With --json, the response is {"total": <n>, "hits": [...]}. Each hit has entry_id, session_id, session_title, entry_kind, content_highlight, decision, captured_at, and relevance_score.

When the search service is not configured or not available, the API returns 503. The CLI then prints search service unavailable, falling back to client-side filter to standard error. The fallback reads every session page you can see and the entries of each session, and does a case-insensitive substring match. It applies --since, --until, and --limit in the CLI. It prints {"results": [...]} with session_id, session_title, entry_kind, content (at most 120 characters), and timestamp. Text output works for fallback results. Other error statuses stop the command without a fallback.

Examples

verdictan history search --query "deployment error" --json
verdictan history search --query "timeout" --entry-kind chat --json
verdictan history search --query "budget" --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --json

verdictan history share

verdictan history share adds a user or team to one session. Only the session owner or an organization admin can manage members.

Usage

verdictan history share <session-id> (--with <user-id|email> | --with-team <team-id>) [--role collaborator|observer] [--json]

Options

Flag	Description
<session-id>	Required. The session ID.
--with <user-id|email>	User UUID or organization member email. An email lookup needs access to the organization user list.
--with-team <team-id>	Team UUID. Use this or --with, not both.
--role <collaborator|observer>	Member role. The default is collaborator.

The CLI sends user_id or team_id to POST /v1/history/sessions/{id}/members. An email is resolved to a user ID before the write. An email that matches no member stops the command.

Examples

verdictan history share 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --with 0e959678-8740-482b-890e-05aa61884664

verdictan history replay

verdictan history replay is deprecated because the API has no replay endpoint. It stops before it sends a request and tells you to export the session. This prevents a misleading partial replay.

Usage

verdictan history replay <session-id> [--gateway-id <id>] [--json]

Options

Flag	Description
<session-id>	Required. The session ID.
--gateway-id <id>	Retained for command compatibility. No request is sent.

Use verdictan history export <session-id> --format json to save the captured requests. Send selected requests through the gateway with your application client. These are new requests and can incur provider charges.

Examples

verdictan history replay 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c

verdictan history stats

verdictan history stats reads all matching session pages and calculates counts locally. It does not call an aggregate stats endpoint.

Usage

verdictan history stats [--team-id <id>] [--agent-id <id>] [--since <rfc3339>] [--until <rfc3339>] [--json]

Options

Flag	Description
--team-id <id>	Count only sessions for this team.
--agent-id <id>	Count only sessions for this agent.
--since <rfc3339>	Count only sessions with last_activity_at at or after this time. An invalid timestamp stops the command.
--until <rfc3339>	Count only sessions with last_activity_at at or before this time. An invalid timestamp stops the command.
--scope <user|team|org>	Deprecated. The CLI prints a warning. Use --team-id or --agent-id to filter.

The summary has total_sessions, total_entries, allowed_entries, blocked_entries, avg_session_length, top_agents, and top_models. Model counts use each session's last_model. The result does not claim token or cost totals, because the session records do not supply them.

Examples

verdictan history stats
verdictan history stats --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --json

verdictan history learn

verdictan history learn calls the supported session-condense API. It returns the server's summary, session ID, and entry count. Use --dry-run to inspect the source entries without creating a summary.

Usage

verdictan history learn [--bind-to-session <id>] [--team-id <id>] [--agent-id <id>] [--min-entry-count <n>] [--dry-run] [--json]

Options

Flag	Description
--bind-to-session <id>	Use this session. Without this flag, the command picks the session with the latest last_activity_at on the first sessions page.
--team-id <id>	Session discovery filter for one team.
--agent-id <id>	Session discovery filter for one agent.
--scope <user|team|org>	Deprecated. The CLI prints a warning. It does not apply this filter.
--min-entry-count <n>	Minimum entry count passed to the API.
--strategy, --previous-sessions-max, --target-max-tokens	Deprecated. The CLI prints a warning and does not send these values.
--dry-run	Read the first 500 entries of the session and print a preview. The command sends no learn request.

With --dry-run, text output prints the session ID and the number of entries fetched. JSON output also contains min_entry_count and the entries array.

Without --dry-run, the command sends POST /v1/history/sessions/{id}/condense with the optional min_entry_count. The API controls authorization and condensation. When discovery finds no session, the command stops with a clear error.

Examples

verdictan history learn --bind-to-session 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --dry-run
verdictan history learn --agent-id bcb8904e-d692-42bd-a176-bc5d408405b4 --dry-run --json

verdictan history condense

verdictan history condense extracts request and response text into a local artifact. It does not call a model or change the server session.

Usage

verdictan history condense [--session-id <id> | --team-id <id> | --agent-id <id>] [OPTIONS]

Options

Flag	Description
--session-id <id>	Condense this session. Without this flag, the command reads matching session pages, up to --max-sessions (default 50).
--team-id <id>	Session filter for one team.
--agent-id <id>	Session filter for one agent.
--scope <user|team|org>	Deprecated. The CLI prints a warning. Use --team-id or --agent-id to filter.
--since <rfc3339>	Keep only sessions with last_activity_at at or after this time.
--until <rfc3339>	Keep only sessions with last_activity_at at or before this time.
--strategy <extract|condense|hybrid>	The default is extract. All three values run the same extraction.
--target-max-tokens <n>	Token budget. The CLI counts four characters for each token. The default is 1200.
--allowed-only	Keep only entries with decision allowed. This is the default.
--include-blocked	Include entries with all decisions. Cannot be combined with --allowed-only.
--output <path>	Write the artifact JSON to this file.
--dry-run	Print counts, not the artifact.

The command reads the first 500 entries of each selected session. It uses the History decision, request_payload, and response_payload fields. It extracts the last user message and the first assistant response when available. The token budget is an estimate, not a model tokenizer. If no readable eligible content exists, it stops with an error. Use export for a complete session copy.

Examples

verdictan history condense --session-id 7f92ff69-7b29-4f2d-a8bb-766c06e61d3c --dry-run

Limits and failure behavior

• list-sessions reads up to its requested limit. stats reads all matching sessions. condense reads up to --max-sessions.
• get-session reads all entry pages with --include-entries. learn --dry-run and condense read at most the first 500 entries. Use export for completeness checks.
• export exits with an error and writes no file when pagination is incomplete or out of order.
• condense continues when it cannot read the entries of one session. It prints warning: could not fetch entries for session <id>: <error> to standard error.
• The scope value in text output is always -.

Troubleshooting

Symptom	Cause	Fix
missing api token (set VERDICTAN_API_TOKEN or run `verdictan auth login`)	No token in the environment or the profile.	Set VERDICTAN_API_TOKEN, or run verdictan auth login.
api authorization failed (403)	You do not have history:read and are not a member of the session. For search, you do not have the organization-level history:read.	Ask an administrator for history:read, or for session membership.
api validation failed (422) on get-session or export	The session ID is not a UUID (history.invalid_id).	Copy the session_id from list-sessions.
api validation failed (422) on list-sessions	--team-id or --agent-id is not a UUID.	Use the UUID of the team or agent.
api request failed with status 404 on get-session or export	The session does not exist in your organization (history.not_found).	Check the session ID and the profile.
history replay reports that it is deprecated	The API has no replay endpoint.	Export the session and send selected requests through your application client.
invalid --since value: ...	The value is not an RFC 3339 timestamp.	Use a value such as 2026-09-01T00:00:00Z.
search prints no results	No accessible captured content matched the query.	Check the filters and the capture settings for the session.
history entries pagination ended after <n> entries, ...	The API returned fewer entries than the session reports.	Run export again. If it fails again, compare with get-session --json.

Next steps

• Export Evidence for a Review: include a session export in an evidence package.
• verdictan agent: find the agent IDs for the --agent-id filters.
• Permissions Reference: check which roles grant history:read and history:write.
• CLI Command Groups: find related commands for the History workflow.