Backup & export

Your data never needs a support ticket to leave the box. 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
`datasets`	Evaluation datasets with their cases
`feedback`, `outcomes`	End-user votes and reported real-world outcomes (ground truth)
`session-scores`	Whole-session judge scores
`patterns`, `online-evaluators`, `custom-evaluators`	Scorer configuration: your patterns, LLM judges, code/external scorers

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.

Exporting

from agentx import AgentX

client = AgentX(api_key="agtx_...")

# 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=...) only moves the delta.

Restore runbook

There are two supported restore paths. 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)

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.

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")
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).

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

Backup & export

What’s exportable

Exporting

Restore runbook

Path 1: database-level (full instance restore)

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

Suggested schedule

​What’s exportable

​Exporting

​Restore runbook

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

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

​Suggested schedule

What’s exportable

Exporting

Restore runbook

Path 1: database-level (full instance restore)

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

Suggested schedule