> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.
# Query execution data
> Synchronize runs, context lineage, events, signals, actions, logs, traces, and outputs into local PostgreSQL and query them with SQL.
Automate.ax can synchronize the execution history you can access into a private local PostgreSQL database. Use standard SQL to investigate failures, follow fan-out across contexts, and inspect events, signal coordination, action results, logs, traces, and explicit automation outputs.
Log in, then synchronize the last seven days:
```bash theme={null}
bunx automate.ax login
bunx automate.ax data sync
```
Limit the dataset with organization or project IDs, names, or slugs, or select a different history window:
```bash theme={null}
bunx automate.ax data sync --project proj_01... --since 30d
bunx automate.ax data sync --org org_01... --since 2026-08-01T00:00:00Z
bunx automate.ax data sync --project proj_01... --since all
```
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.
## Discover the authorized resources
The command-line tool reads the public execution-data manifest through the same typed client and bearer session as other management commands. You can inspect it through REST when building another agent interface:
```bash theme={null}
curl --get https://automate.ax/api/v1/execution-data/manifest \
--header "Authorization: Bearer $AUTOMATE_SESSION_TOKEN" \
--data-urlencode "projectId=proj_01..." \
--data-urlencode "since=2026-08-01T00:00:00Z"
```
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 logs and traces
Action handlers receive durable logging and tracing methods on their runtime:
```ts theme={null}
import { defineAction } from "automate.ax"
import { z } from "zod"
export const processOrder = defineAction("Process order")
.input(z.object({ orderId: z.string() }))
.handler(async ({ input, runtime }) => {
await runtime.trace(
{ attributes: { orderId: input.orderId }, name: "Charge order" },
async () => {
await runtime.log({
fields: { orderId: input.orderId },
level: "info",
message: "Charging order",
})
},
)
})
```
Await these methods when persistence must finish before the action continues. Each action attempt can write 1,000 logs and 250 spans. Messages allow 16,384 characters, span names allow 256 characters, and field or attribute maps allow 64 entries and 64 KiB encoded. Each field or attribute key allows 128 characters. Exceeding a limit fails the method. Deterministic per-attempt indexes make repeated delivery idempotent while preserving logs and spans from every retry.
Nested `trace` callbacks create parent-child spans. Logs automatically record their active span. A callback that throws marks its span failed with a normalized error and throws the original error again. An abrupt sandbox exit can leave a span in `running`, which identifies unfinished work. Logs and traces don't replace or change explicit automation outputs.
## Query the data
Pass a statement directly or use a SQL file:
```bash theme={null}
bunx automate.ax query --sql "
SELECT project_name, automation_identity_key, status, created_at
FROM automate.runs
WHERE status = 'failed'
ORDER BY created_at DESC
LIMIT 20
"
bunx automate.ax query --file investigation.sql --json
```
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:
```bash theme={null}
bunx automate.ax data schema
bunx automate.ax data schema --sql
bunx automate.ax data status --json
```
## Follow context 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:
```sql theme={null}
SELECT
descendants.depth,
outputs.context_id,
outputs.type,
outputs.data,
outputs.created_at
FROM automate.context_descendants AS descendants
INNER JOIN automate.outputs
ON outputs.context_id = descendants.descendant_context_id
WHERE descendants.context_id = 'actx_01...'
ORDER BY outputs.output_seq;
```
The `automate.runs` view contains root contexts—contexts without a parent—joined to their automation, project, and organization identity. The `automate.contexts` table contains both roots and continuations.
## Investigate logs and traces
Find recent warnings and errors with their action and span provenance:
```sql theme={null}
SELECT
created_at,
level,
message,
context_id,
action_invocation_id,
attempt,
span_index,
fields
FROM automate.logs
WHERE level IN ('warn', 'error')
ORDER BY created_at DESC
LIMIT 100;
```
Follow every nested span beneath one root span:
```sql theme={null}
SELECT
lineage.depth,
spans.name,
spans.status,
spans.started_at,
spans.completed_at,
spans.attributes,
spans.error
FROM automate.trace_span_descendants AS lineage
INNER JOIN automate.trace_spans AS spans
ON spans.id = lineage.descendant_span_id
WHERE lineage.span_id = 'aspan_01...'
ORDER BY lineage.depth, spans.started_at;
```
## Tables
| Object | Contents |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `automate.projects` | Projects in the synchronized scope. |
| `automate.automations` | Automation identity and enabled state. |
| `automate.contexts` | Root and continuation context lifecycle. |
| `automate.context_parents` | Direct context directed acyclic graph edges. |
| `automate.event_links` | Events attached to contexts with hook provenance. |
| `automate.events` | Event metadata and decoded payload projection. |
| `automate.actions` | Action lifecycle, dependencies, failures, and output projection. |
| `automate.signal_invocations` | Signal lifecycle, dependency IDs, selected index, failure, and output projection. |
| `automate.signal_coordinators` | Durable coordinator identity, location, configuration hash, and parent precedence. |
| `automate.signal_offers` | Correlation lanes, exact keys, dependency IDs, timing, selection, and outcome status. |
| `automate.signal_decisions` | Decisions that match coordinator offers to contexts. |
| `automate.logs` | Ordered user-authored logs with action-attempt and active-span provenance. |
| `automate.outputs` | Explicit ordered outputs from automation code. |
| `automate.trace_spans` | Per-attempt nested spans, attributes, status, and failures. |
| `automate.runs` | Root contexts joined to automation and project identity. |
| `automate.context_ancestors` | Transitive parent relationships and depth. |
| `automate.context_descendants` | Transitive child relationships and depth. |
| `automate.trace_span_ancestors` | Transitive parent-span relationships and depth. |
| `automate.trace_span_descendants` | Transitive child-span relationships and depth. |
| `automate.signal_outcomes` | Joined signal, decision, coordinator, and selected-offer results for races, correlations, collects, fan-outs, and funnels. |
## Payload representation
Automate.ax payloads support values that JSON can't represent directly. The `payload`, `output`, `key`, `data`, `value`, `fields`, and `attributes` 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.
Use JSON operators normally:
```sql theme={null}
SELECT id, payload->>'customerId' AS customer_id
FROM automate.events
WHERE event_type = 'stripe.customer.updated';
```
## Keep data current
Run a live synchronization process while investigating active automations:
```bash theme={null}
bunx automate.ax data follow --project proj_01... --since 1d
```
Press Ctrl+C to stop. The local database remains available for later queries.
Electric makes each synchronized resource current at its own shape offset; it does not 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.
## Local-data safety
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 it explicitly:
```bash theme={null}
bunx automate.ax data export --output ./execution-data.tar.gz
bunx automate.ax data clear
```
Treat exported archives as sensitive. `data clear --yes` supports non-interactive cleanup.