Skip to content

Subject erasure

POST /erasures deletes one subject’s rows from one project. One subject per request. The route is available on all plans, including free.

Call it only when the person asked to delete that subject’s data. Keep it out of a normal analytics loop.

On hosted, erasure needs manage or admin.

A dashboard session cookie can erase. A project key (aapk_*) can erase when its level is manage or admin, and only inside its one project. A read level receives 403 FORBIDDEN_SCOPE on GET /erasures and on POST /erasures.

The legacy account key (aak_*) can no longer erase. POST /erasures and GET /erasures with aak_ return 403 FORBIDDEN_SCOPE with message account API key cannot erase; use a project key or agent session with manage or admin.

A session limited to one project can erase only in that project. Naming another project returns 404 PROJECT_NOT_FOUND. Email erasure with portfolio: true stays inside the granted project.

Each level expands to scopes, so a session without erasures:write still fails the scope check. That response is 403 FORBIDDEN with message agent session missing required scope: erasures:write. analytics:read and projects:write are not enough. read does not include erasures:write. manage and admin do.

Legacy sessions keep working. A legacy session keeps its stored scopes and all-projects access. One that already has erasures:write can still erase.

The demo project stays read-only: 403 DEMO_READ_ONLY. The MCP tool is absent from the demo MCP.

These level rules are hosted. On the self-hosted server, whoever holds API_KEYS can still erase. A project string is not an authorization boundary there. See Self-hosted OSS server.

An account can accept 20 erasures per hour. The cap is separate from the requests-per-minute limit. An erasure is not metered as a read, and it does not move the monthly read counter. The next accept after 20 in that hour is 429 RATE_LIMITED with reason: "erasure_rate_limit". Reading a receipt does not spend the cap.

POST /erasures requires project, idempotency_key, and confirm set to the string erase. Send exactly one of user_id, session_id, or email.

{
"project": "my-site",
"idempotency_key": "erase-user-123-2026-11-13",
"confirm": "erase",
"user_id": "user_123",
"include_replays": true
}

include_replays defaults to true.

user_id matches that id on events (user_id and resolved_user_id), sessions (user_id and resolved_user_id), identity_map (previous_id and canonical_id), identity_aliases (alias_id and canonical_id), and user_profiles.user_id, inside this project. The job walks identity_map and identity_aliases once and deletes the linked ids too. It then deletes events, sessions, identity rows, profiles, and email_lookup_index rows for this project only.

session_id deletes events, sessions, and replay for that session. There is no identity graph walk.

email is normalized and HMAC’d the same way project email lookup is built. Matching lookup rows supply user ids, and the user_id path runs from there. The raw email is not stored on the job and is not returned. portfolio applies only to email and defaults to false, so the delete stays inside the named project even when that project belongs to a portfolio. portfolio: true uses the portfolio HMAC and loops that portfolio’s member projects.

{
"project": "my-site",
"idempotency_key": "erase-visitor-email-2026-11-13",
"confirm": "erase",
"email": "visitor@example.com",
"portfolio": true
}

Event and session deletes use the project name. Email lookup deletes use scope_id = project:<uuid>. A second project in the same database is left untouched, including when it stores the same user ids. Rows whose properties merely contain the id are left in place.

confirm_large: true is required when the subject matches more than 100,000 events. The pre-count is COUNT(*) on events for that id. Without it the response is 400 CONFIRM_LARGE_REQUIRED.

A missing confirm, two subject fields, an empty subject, or a subject longer than 256 characters is 400 INVALID_ERASURE.

The same idempotency_key and the same body return the original job. A retry of a failed job continues that job. The same key with a different body is 409 IDEMPOTENCY_CONFLICT.

200 means the job finished inside the request. 202 means it is still running. Poll GET /erasures/{id}. GET /erasures?project= returns the 100 newest receipts for that project. Receipts carry subject_type and counts. They omit the subject value, event payloads, and the raw email.

{
"id": "era_01HZX",
"status": "completed",
"project": "my-site",
"subject_type": "user_id",
"counts": {
"events": 12,
"sessions": 2,
"identity_rows": 3,
"profiles": 1,
"email_lookups": 1,
"replay_sessions": 1,
"replay_objects": 4
},
"replay_included": true,
"completed_at": "2026-11-13T18:04:11.000Z"
}

status is pending, running, completed, or failed. A finished failure uses 200 with status: "failed" and error. Hosted replay deletes run when include_replays is true. Self-hosted runs the same route synchronously inside the request, so the response is 200 when the delete finishes.

Usage counters, bot-traffic rows, HMAC secrets, and project-context notes stay. The secrets are what a later erasure of the same email uses. The erasure path does not log the subject.

Hosted writes a tombstone for the account, the project name, the SHA-256 of each id, and the email HMAC. Late events for an erased id are dropped for 7 days. After those 7 days, a new event with the same id is stored again. Erasure is a delete of the rows that exist now, and the 7-day window is the only drop period.

Audit rows keep hashes for 24 months. Hashes are still identifiers. Each row stores subject_hash, status, counts, and requested_by (api_key, session, or agent_session plus the session id). It does not store the raw subject, property JSON, or replay bytes. The row is deleted after 24 months. Tombstones expire at 7 days.

A database restore can bring erased rows back for up to 30 days. Ask support to re-apply erasures after any restore.

Hosted writes each completed receipt, without the raw subject, to erasures/{accountId}/{id}.json. Support re-applies from those receipts with scripts/reapply-erasures.mjs. That command is manual and stays outside the request path. On the self-hosted server, re-apply after restoring a SQLite snapshot or a D1 Time Travel bookmark. See Self-hosted OSS server.

Status Code When
400 INVALID_ERASURE Missing confirm, two subjects, an empty subject, or a subject longer than 256 characters
400 CONFIRM_LARGE_REQUIRED The subject matches more than 100,000 events and confirm_large is not true
403 FORBIDDEN_SCOPE read, or an account key (aak_). The account key message is account API key cannot erase; use a project key or agent session with manage or admin
403 FORBIDDEN Agent session without erasures:write. Message: agent session missing required scope: erasures:write
403 DEMO_READ_ONLY Demo project
404 PROJECT_NOT_FOUND Project is missing
409 IDEMPOTENCY_CONFLICT Same idempotency_key, different body
429 RATE_LIMITED reason: "erasure_rate_limit" after 20 accepts in an hour
Terminal window
aa erase my-site --user-id user_123 --confirm erase
aa erase my-site --session-id sess_123 --confirm erase
aa erase my-site --email visitor@example.com --confirm erase
aa erasures my-site
aa erasures get era_01HZX

Pass --idempotency-key when you already have one. When the flag is absent, the CLI generates a key and prints it.

The MCP tool erase_subject has readOnlyHint: false and destructiveHint: true. It requires confirm set to erase. It is registered only at manage or admin, when the session scopes include erasures:write. The tools that read GET /erasures and GET /erasures/{id} are read-only. Agent sessions still need manage or admin (erasures:write) on those routes. A 404 or 403 comes back as clear error text. When the CLI level is too low, erase and erasures print a clear hint to use manage or admin.