Backup & export

Every project-scoped table streams out of the engine as NDJSON over one authenticated endpoint, and the same endpoint powers client.export in the Python SDK.

What’s exportable

GET /api/v1/export (with your project’s x-api-key) returns a manifest of every entity with live row counts. GET /api/v1/export/<entity> streams the rows, one JSON object per line, in exactly the stored shape (timestamps as ISO-8601):

Entity	Contents
`traces`	Every trace/span row: input, output, tokens, latency, session and span ids, metadata
`signals`, `signal-feedback`	Triage signals and the human verdicts recorded on them
`events`, `classifications`	Scorer/evaluator event history and topic classifications
`runs`, `run-results`, `gate-results`	Evaluation runs, per-case results, CI gate verdicts
`pairwise-comparisons`	Head-to-head judge verdicts between runs
`datasets`	Evaluation datasets with their cases
`evaluation-settings`	Grading configs: the judge rubric + profile behind each dataset run and online evaluator
`dataset-versions`, `evaluation-settings-versions`	Version histories: every recorded edit to a dataset or grading config
`evaluation-analyses`	The AI analysis narratives generated for runs (strengths, weaknesses, recommendations)
`review-queue`	Human review-queue items with their labels and corrected scores
`feedback`, `outcomes`	End-user votes and reported real-world outcomes (ground truth)
`session-scores`	Whole-session judge scores
`patterns`, `online-evaluators`, `custom-evaluators`, `rules`	Scorer configuration: your patterns, LLM judges, code/external scorers, automation rules
`scorer-groups`	Composed graders: members, weights, gates, and the online profile
`alert-rules`, `alert-events`	KPI alert rules and their notification history with per-channel delivery results
`prompts`, `prompt-versions`	The Improve loop’s prompt registry with its full version history
`tool-schemas`, `tool-schema-versions`	The Improve loop’s tool schema registry with its full version history
`improvement-proposals`, `improvement-groups`, `improvement-group-members`	Improvement proposals and the groups that cluster them
`improvement-reports`	Generated improvement reports (LLM output already paid for)
`agents`, `monitor-profiles`	Tracked agents and their per-agent monitoring profiles (webhook channels included)
`agent-connectors`	HTTP agent connector registrations (header values redacted, see below)
`playground-profiles`	Saved Playground configurations
`playground-runs`	Saved Playground runs
`audit-events`	The instance’s audit log, scoped to the project

Connector secrets are redacted. Bearer tokens live in agent-connector header values, so the export keeps the header keys but replaces every value with ***redacted*** - and does the same to credentials embedded in the connector URL (userinfo and every query-string value). After a restore, re-enter the secrets - same as provider API keys, which are excluded from the export entirely. Webhook URLs in rules, monitor-profiles, and alert-rules get the same treatment - userinfo, query values, and the path tail after the first segment are masked - and an alert rule’s PagerDuty routing key is exported masked. External-scorer URLs in custom-evaluators keep their path (it is the scorer’s route, not a secret) and only lose userinfo and query values.

Config tables ride along with the data because a usable backup is the data plus the scorer configuration that produced it. Everything is scoped to the API key’s project: an export can never cross a tenant boundary. Instance-wide state (auth users/orgs, app settings, the pricing catalog) is deliberately not in the project export; it belongs to the database-level backup below. Per-project settings travel separately from the /export manifest: GET /api/v1/export/project-settings returns the project row’s own behavior knobs (retention, thresholds, topics sampling, enabled built-in patterns) as one NDJSON line, with the apiKey stripped - the export stream is never the surface that hands the credential out. Fetch it alongside the entity dump if you want a complete picture of the project.

Exporting

from agentx import AgentX

client = AgentX(
    api_key="agtx_...",
    base_url="http://localhost:4700/api/v1",  # or AgentX.from_env() with AGENTX_API_BASE_URL set
)

# Full backup: one <entity>.ndjson per entity + manifest.json
client.export.dump("./backup-2026-08-22")

# Incremental (entities filter on their own timestamp column)
client.export.dump("./nightly", since="2026-08-21T00:00:00Z")

# Stream without touching disk
for row in client.export.iter("traces"):
    ...

# Manifest with row counts
curl -H "x-api-key: $KEY" http://localhost:4700/api/v1/export

# One entity, incrementally
curl -H "x-api-key: $KEY" \
  "http://localhost:4700/api/v1/export/traces?since=2026-08-21" \
  -o traces.ndjson

Exports are keyset-paginated internally, so memory stays flat on both ends regardless of table size, and a nightly dump(since=...) moves only the delta for most entities. The one caveat: signals filters on lastSeenAt, so a long-lived signal that keeps re-firing reappears in each incremental. A failed export never truncates silently: if the stream breaks mid-flight the engine destroys the socket, so the client sees a broken transfer instead of a clean end. Treat a truncated .ndjson file as a failed backup and re-run the export.

Restore runbook

There are three supported restore paths: database-level restore, replay through ingest, and dataset import. There is deliberately no blind row-level import endpoint: one would bypass the engine’s invariants (span dedupe, id uniqueness, derived agent rows) and could corrupt a live project silently.

Path 1: database-level (full instance restore)

In the SQLite and Postgres tiers the engine owns exactly one database; restoring it restores everything, including auth and settings.

SQLite (default): stop the engine, copy $AGENTX_HOME/agentx.db back into place, start the engine. For hot backups use sqlite3 agentx.db ".backup backup.db" which is safe while the engine runs.
Postgres: standard pg_dump / pg_restore (or your provider’s point-in-time recovery). The engine runs its own migrations at boot, so restoring an older dump into a newer engine is supported; the reverse is not.
Enterprise tier (Postgres + ClickHouse): the control plane is the Postgres backup above; spans live in ClickHouse and are append-only, so incremental strategies work well - a native format dump (SELECT * FROM agentx_spans FORMAT Native), clickhouse-backup, or volume snapshots. Restore into a fresh table (the engine creates it on boot) with INSERT INTO agentx_spans FORMAT Native.

Path 2: replay (project-level, cross-instance migration)

NDJSON exports replay through the normal ingest surface into any project on any instance:

import json
from agentx import AgentX

target = AgentX(
    api_key="agtx_target_project_key",
    base_url="http://target-host:4700/api/v1",  # defaults to the hosted SaaS URL otherwise
)
with open("backup/traces.ndjson") as fh:
    for line in fh:
        row = json.loads(line)
        with target.tracer.trace(
            row["name"], input=row["input"],
            session_id=row.get("sessionId"), metadata=row.get("metadata"),
        ) as span:
            span.output = row["output"]

Replay is how the engine’s own round-trip test verifies the export contract: export a seeded project, replay it into a fresh one, and the counts and contents match. Ground truth (feedback, outcomes) replays the same way through client.feedback / client.outcomes. Note what replay preserves and what it does not: content, sessions, span trees, and metadata survive; engine-assigned row ids and createdAt are newly assigned on the target (the original timestamps remain inside the exported file if you need them).

Path 3: dataset import & delete

Datasets get a first-class replay path of their own: POST /api/v1/evaluate/datasets/import takes a row from the datasets NDJSON export, wrapped as {"dataset": {...}}, and recreates it - cases, grading config, similarity flags - as a new dataset with fresh ids (201). It is a copy, never an in-place restore, so importing can’t clobber a live dataset:

head -1 backup/datasets.ndjson | jq '{dataset: .}' | \
  curl -X POST http://localhost:4700/api/v1/evaluate/datasets/import \
    -H "x-api-key: $KEY" -H "Content-Type: application/json" -d @-

The reverse also exists: datasets can be deleted from the dashboard. Deleting removes the dataset, its grading config, and both version histories; past runs are kept - run history is your record of what was measured, not part of the dataset. A dataset whose grading config is still bound to a live online evaluator refuses deletion (409) until the scorer is detached.

Suggested schedule

Nightly: client.export.dump(dir, since=<24h ago>) to object storage - the incremental NDJSON is your audit-friendly, vendor-neutral copy.
Weekly: database-level backup (SQLite .backup file or pg_dump) - the fast full-restore path.
Before upgrades: database-level backup, always; the engine migrates forward only.

Get Started

Self-Hosting

Python SDK

Guides

Backup & export

What’s exportable

Exporting

Restore runbook

Path 1: database-level (full instance restore)

Path 2: replay (project-level, cross-instance migration)

Path 3: dataset import & delete

Suggested schedule

​What’s exportable

​Exporting

​Restore runbook

​Path 1: database-level (full instance restore)

​Path 2: replay (project-level, cross-instance migration)

​Path 3: dataset import & delete

​Suggested schedule

What’s exportable

Exporting

Restore runbook

Path 1: database-level (full instance restore)

Path 2: replay (project-level, cross-instance migration)

Path 3: dataset import & delete

Suggested schedule