STACK
MENU
DOCS / CONTROLS / THE RECORD

The record

How you read what your agents did, export it, check that nothing was changed, hand a signed pack to an auditor, and have the record delivered to your own systems as it is written. What the record is and what it costs is on Controls.

Before you start

Every action of every account is written to the record, with controls on or off. Reading it needs controls. Without them each call here answers 402 CONTROLS_REQUIRED. When you switch controls on, the whole record is there, including what was written before.

Read it

prompt
What did the assistant agent do in the last hour?

The client calls stack_audit_list. From code or the terminal:

typescript
const { entries } = await stack.audit.list({ limit: 50, agentId: 'agt_123' });
bash
# The newest entries.
npx @getstackrun/cli audit list --limit 50 --agent agt_123

# Follow one agent live.
npx @getstackrun/cli monitor --follow --agent agt_123
  • Entries come newest first, up to 100 a call. since returns the entries from a time onward.
  • Filter by agent_id or by passport_jti.
  • An agent can read only its own entries. Exporting and checking are for a person or a key.

Export it

bash
npx @getstackrun/cli audit export --format csv --from 2026-10-01T00:00:00Z --to 2026-11-01T00:00:00Z --out october.csv
  • The formats are json, ndjson and csv.
  • One export holds up to 50,000 rows. Use offset for the next page.
  • The tool is stack_audit_export. There is no SDK method for an export: use the terminal, the tool or GET /v1/audit/export.
  • The record is kept 365 days. Rows older than that are gone.

Check that nothing was changed

Each entry carries a hash of the entry before it, so a changed or removed entry breaks the chain.

typescript
const head = await stack.audit.chainHead();   // head.latest_entry_hash, head.total_entries
const check = await stack.audit.verifyChain(); // check.valid, check.first_break
  • verify-chain walks the entries and reports the first break, if there is one.
  • chain-head returns the newest hash and the count. Store it somewhere STACK cannot reach, on a schedule. If an entry is changed later, a new check will not match what you stored.
  • The tools are stack_audit_verify_chain and stack_audit_chain_head. From the terminal: audit verify-chain and audit chain-head.

Hand a signed pack to an auditor

bash
# One Mission, or a period.
npx @getstackrun/cli evidence-pack export --scope mission:ms_abc --output pack.json
npx @getstackrun/cli evidence-pack export --scope period:2026-Q3 --output q3.json

# The auditor checks it, with no STACK account.
npx @getstackrun/verify pack.json
  • A scope is mission:<id>, session:<id> or a period: period:2026-Q3, period:2026-10 or period:2026-10-01/2026-10-31. From code the ref of a period carries the word too: kind "period", ref "period:2026-Q3".
  • The verifier is its own open package. It checks the signatures, the hashes and the links between entries, offline.
  • It exits 0 when the pack is valid and 1 when it is not.
  • The tool is stack_export_signed_record. From code: stack.evidencePacks.export({ scope: { kind, ref } }).
  • stack_list_signed_records and stack_download_signed_record find and fetch a pack made earlier.

Have it delivered to your own systems

STACK can send each entry to an address of yours as it is written, in order, in signed batches. Setting the address needs your approval in a browser.

bash
npx @getstackrun/cli control-socket set-events https://logs.example.com/stack
npx @getstackrun/cli control-socket verify events
  • The address must be https on a public host. The first set prints a signing secret once.
  • verify sends one signed test batch. Any 2xx answer starts delivery.
  • A batch holds up to 100 entries. Each entry has a number, seq, with no gaps, so you can tell if one is missing.
  • A batch is sent again until your server answers 2xx. A batch your server refuses three times is set aside, and one entry in the stream says which numbers were skipped. After 72 hours of failures delivery pauses and you are told.
  • An entry carries what happened and its hashes. It never carries message text, secrets or card numbers.
  • Check each batch with verifyWebhook from the SDK, or any Standard Webhooks library.

Delivery, like reading, needs controls, or your own decision server. With neither, nothing is sent, and the address stays set for when they are on.

What counts as an action

Nothing here is an action. Reading, exporting, checking, packs and delivery are free with controls.

When it is refused

  • 402 CONTROLS_REQUIRED - controls are off.
  • 403 FORBIDDEN - an agent asked for another agent's entries, or for an export.
  • 429 - more than 30 exports a minute.
  • 400 on a pack - the scope is not one of the forms above.
  • 400 CONTROL_SOCKET_ADDRESS_REFUSED - the delivery address is not https on a public host.

Reference

How the chain is built is in Audit Log. Every field is on Audit and Evidence.

The record | Docs