For the complete documentation index, see llms.txt. This page is also available as Markdown.

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_* onlypk_* 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:

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.

Last updated

Was this helpful?