The Automate.ax CLI queries a private local PostgreSQL copy of the runs you can access. Use ranked full-text search to find likely matches, then use SQL for exact filtering and joins across failures, fan-out, events, signal coordination, actions, logs, and explicit automation outputs.
Inspect a run in the dashboard
Open a recent execution to follow its causal timeline from left to right. Trigger occurrences and action invocations appear in execution lanes; connections show branches and joins. Long gaps are compressed and labeled with their actual duration. Select an operation output to preview and navigate its value.
A run appears Waiting while an internal delay has not been delivered. The initiating context may already have settled. The delayed delivery starts an independent root; the dashboard connects it to the initiating occurrence only after correlation creates a shared child.
markSignificant highlights the causally connected run when a chosen signal emits. Recent runs then hides insignificant runs by default. Turn on Show insignificant runs to see the complete history. Automations without a significance marker remain unfiltered.
Query runs locally
For a one-time investigation, log in and synchronize the last seven days for the nearby project:
The command always synchronizes one project. Without an explicit scope, it uses a nearby project config or asks you to choose.
Pass a project ID or name to select it directly. Pass an organization ID, name, or slug to limit project selection to that organization. You can also select a different history window:
The default seven-day window keeps the first download bounded. --since all is an explicit request for every retained execution in the selected scope. The server applies your account’s project access before synchronization. Local options can narrow that access but can’t widen it.
A bounded window also includes the older ancestors of matching contexts. This keeps causal lineage and fan-out traversal intact without synchronizing unrelated old runs.
While testing an automation, keep data follow running in a separate terminal:
Wait for Following execution data before invoking the automation. Press Ctrl+C to stop after the investigation. The local database remains available for later queries.
Local execution-data commands coordinate database access. Queries, searches, status checks, exports, synchronization, and cleanup wait for an in-progress local write, while data follow releases the database between updates. Other terminals and agents can run those commands concurrently against the same local dataset.
Electric makes each synchronized resource current at its own shape offset. It doesn’t provide one transaction boundary across all shapes. The manifest reports consistency: "eventual", and data status --json reports the offset, row count, and synchronization time for every resource. A local update replaces one resource and its freshness marker atomically. When a query joins resources, compare their markers if the newest cross-resource changes must already agree.
Wait for a background HTTP run
For work that fits within the HTTP response window, pass the trigger’s requestId to respondToHttpRequest so the invocation itself returns the result.
Otherwise, an HTTP trigger returns a 202 receipt containing an eventId. Capture that exact event instead of guessing how long the run needs or selecting the newest timestamp:
One event can start several root contexts when a shared endpoint has several active subscriptions. Fan-out and coordination can add descendant contexts beneath each root. Delayed deliveries and protected callbacks create their own roots, and correlation can create a child beneath both the initiating and delivery roots. automate.root_contexts contains only roots. automate.context_descendants maps each root to its current descendants, including the root at depth 0.
In SQL, use root context for that stored lifecycle record. In explanations to end users, call the causally connected workflow a run. root_contexts is query terminology, not product language.
With data follow still running, use Bash and jq to poll until the event has at least one synchronized context, every current context has either settled or failed, and no internal delay is pending or waiting for its delivery context to synchronize. The query follows delivered delays through their invocation provenance. This example stops after five minutes. Increase the deadline for intentionally long automations.
Invocation provenance covers internal delays, not external callbacks or other
provider deliveries. When the expected result depends on one of those roots,
poll for its terminal action or explicit output instead of treating settled
current contexts as workflow completion.
After the query reports no pending internal delay, search for resources that mention the event ID or known failure text. Verify the expected terminal action, output, or external side effect before reporting the run complete:
Use this exact join when you need every context and action associated with the request:
Build a run-history client
The CLI and REST endpoint read the same public execution-data manifest with the same bearer session. Inspect the REST response when building another agent interface:
The response includes the validated scope, local schema version, eventual-consistency mode, opaque profile ID, and one fixed authenticated Electric URL for every resource. Organization and project filters must exist, be related when supplied together, and be visible to the signed-in user. The Electric URLs require that same user session; they don’t accept arbitrary table, column, or predicate parameters.
Record structured logs
The action runtime exposes the durable runtime.log() method:
Await runtime.log() when persistence must finish before the action continues. Each action attempt can write 1,000 logs. Messages allow 16,384 characters, and field maps allow 64 entries and 64 KiB encoded. Each field key allows 128 characters. Exceeding a limit fails the method. Deterministic per-attempt indexes make repeated delivery idempotent while preserving logs from every retry.
Logs retain their action, context, and retry-attempt provenance. They don’t replace or change explicit automation outputs.
Query runs with SQL
Pass a statement directly or use a SQL file:
Search runs
Search synchronized logs, failures, actions, outputs, event payloads, IDs, providers, projects, and automations without writing SQL:
automate search ranks each result and includes its resource, resource ID, context ID, timestamp, and a matching excerpt. Search uses PostgreSQL’s simple text-search dictionary so provider names, action names, and identifiers aren’t stemmed as English prose. Titles and human-authored text receive more weight than structured metadata and IDs. Exact and partial identifier matches receive an additional ranking boost, while pg_trgm recovers misspellings and partial terms.
The derived automate.search_documents table rebuilds from the synchronized tables during data sync and when its local schema changes. data follow refreshes only the search resource affected by each high-volume execution update. The table contains no independent server state.
Use the same index directly from SQL when you need custom filtering or joins:
Combine trigram word similarity with a partial identifier match for typo-tolerant investigations:
The full-text vector and trigram text columns use generalized inverted (GIN) indexes. Automate.ax uses native cover-density ranking and doesn’t load the optional PGlite BM25 extension.
Queries can only read synchronized tables and views in the automate schema. query accepts one or more PostgreSQL SELECT statements and EXPLAIN for a SELECT. It rejects session changes, transactions, modifying common table expressions, row locks, and every data-definition or data-modification statement. Each query also runs as a restricted role inside a read-only transaction.
Inspect the available objects and local status:
Trace fan-out
automate.context_ancestors and automate.context_descendants contain the transitive context relationships, including each context itself at depth 0.
Find every output emitted beneath one context:
The automate.root_contexts view contains contexts without a parent, joined to their automation, project, and organization identity. The automate.contexts table contains roots and coordinated or fan-out child contexts.
Trace delayed and scheduled work
automate.automation_invocations records work scheduled by an action. Join idempotency_key to automate.actions.id to find the scheduling action and its origin context. run_at is the requested delivery time. processed_at remains NULL until delivery processing finishes, and event_id identifies the delivered event when delivery creates one.
Find scheduled invocations originating in a context family:
This provenance doesn’t make the delivery context a child of the origin. Delays, programmatic invocations, callbacks, provider events, and replies still arrive as ordinary roots. Traverse context_parents only after correlation creates an actual shared child. A pending internal delay can make the origin run appear Waiting in the web app. A scheduled programmatic invocation remains independent work.
Investigate logs
Find recent warnings and errors with their action-attempt provenance:
Execution tables
Read non-JSON values
Automate.ax payloads support values that JSON can’t represent directly. The payload, output, key, data, value, and fields columns use an extended JSON projection:
- Ordinary objects, arrays, strings, booleans, numbers, and
null remain ordinary JSON.
- Values such as
bigint, Date, Map, Set, typed arrays, files, requests, and responses use an object with a $type field.
- An ordinary object that already owns
$type is wrapped as { "$type": "object", "value": ... }, so its original tag can’t be confused with the projection format.
- Binary values up to 64 KiB include base64. Larger values include their size, an
omitted marker, and an encodedRef identifying the exact stored value.
- Corresponding
*_encoded columns retain the exact encoded bytes. These columns hold the local copy of server truth. Automate.ax derives the JSON columns for queries.
Query projected columns with PostgreSQL JSON operators:
Protect local run history
The database can contain sensitive provider data. Automate.ax isolates it by app origin and signed-in profile, creates its directory with owner-only permissions, and deletes every local profile for that app origin when you log out—even when the server session has expired.
Export or clear the local database:
data export archives may contain provider payloads, action values, and logs; store them as sensitive data. data clear --yes supports non-interactive cleanup.
If a local execution-data command fails unexpectedly, including with a low-level error such as Aborted(), clear the derived database and download a fresh copy:
Add the --project, --org, and --since options needed to restore your intended scope. Clearing this cache doesn’t change production execution data.
When PostgreSQL reports explicit database corruption, data sync removes that profile’s cache and rebuilds it once automatically. Local read commands remove recognized unusable caches and direct you to synchronize again. The command-line tool preserves other server, authorization, and local filesystem errors.