POST /v1/forget

POST /v1/forget — GDPR delete for a user.

Permanently delete every event for (project_id, user_id). Intended for GDPR / CCPA Right-to-be-Forgotten requests.

Auth

Required scope	ingest or admin
Key kinds	sk_* only — pk_* is explicitly rejected to prevent a leaked browser key from wiping data.

Request

POST /v1/forget
Authorization: Bearer sk_live_…
Content-Type: application/json

{ "user_id": "user_42" }

Field	Required	Notes
user_id	yes	The stable user id you've been tagging events with. 1–256 chars.

Response

{ "ok": true, "queued": true }

The mutation is queued on ClickHouse (ALTER TABLE … DELETE) and typically completes within seconds, occasionally minutes for very large tables.

What gets deleted

• Every row in events where project_id = <your project> and user_id = <user>.
• Aggregated rows in daily_rollup and sessions are not rewritten — they're aggregates, not personal data. If you need to also strip rollup contributions, run a full re-aggregation from the surviving raw events.

What does NOT get deleted

• Anonymous events for the same person before you called /v1/identify. They have no user_id and are indistinguishable from any other anonymous traffic.
• Events under other projects (the deletion is scoped to the project owning the key).

If you need to forget by anonymous_id instead of user_id, run the equivalent SQL directly against ClickHouse:

ALTER TABLE events DELETE
  WHERE project_id = '{project_id}'
    AND anonymous_id = '{anonymous_id}';

Audit

Issue a /v1/forget call from a logged-only context (a script, a request handler with audit logs) — the Worker itself doesn't yet write a structured audit row. That's on the roadmap.

Errors

• 403 forget_requires_secret_key — you used a pk_* key.
• 500 forget_failed — ClickHouse rejected the mutation. Check Worker logs.