> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Backup & export

> Bulk NDJSON export, incremental snapshots, and the restore runbook

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

<CodeGroup>
  ```python Python SDK theme={null}
  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"):
      ...
  ```

  ```bash curl theme={null}
  # 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
  ```
</CodeGroup>

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:

```python theme={null}
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.