persons

This endpoint allows you to bulk delete persons, either by the PostHog person IDs or by distinct IDs. You can pass in a maximum of 1000 IDs per call. Only events captured before the request will be deleted.

Person records are removed in the background shortly after the request returns, so a successful response reports them in persons_queued_for_deletion and persons_deleted is 0.

post/api/projects/{project_id}/persons/bulk_delete/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/persons/bulk_delete/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

format'csv' | 'json'

Request body

idsstring[]

A list of PostHog person UUIDs to delete (max 1000).

distinct_idsstring[]

A list of distinct IDs whose associated persons will be deleted (max 1000).

delete_eventsboolean

If true, queue deletion of all events associated with these persons.

delete_recordingsboolean

If true, queue deletion of all recordings associated with these persons.

keep_personboolean

If true, keep the person records but delete their events and recordings.

Response

persons_foundinteger required

Number of persons matched by the provided IDs or distinct IDs.

persons_deletedinteger required

Number of person records deleted from the database during this request. 0 if keep_person was true or if the deletion was queued (see persons_queued_for_deletion).

persons_queued_for_deletioninteger required

Number of persons queued for deletion in the background. Their person records and distinct IDs are removed shortly after the request completes. 0 if keep_person was true.

events_queued_for_deletionboolean required

Whether event deletion was requested for the matched persons. If a deletion was already queued for a person, it will not be duplicated.

recordings_queued_for_deletionboolean required

Whether recording deletion was requested for the matched persons. If a deletion was already queued for a person, it will not be duplicated.

deletion_errorsobject[]

Persons whose deletion did not fully complete in this request. Each entry contains 'person_uuid' and 'step', the deletion step that failed for that person. Failures are reported here rather than as an error status, so a 202 with entries means those persons were not deleted and the request should be retried for them. Two steps are exceptions, and retrying won't find these persons. For 'log_activity', the person was deleted, but the activity log entry was not written. For 'publish_clickhouse_tombstone', the person was deleted, but it can still show in analytics until a weekly cleanup job removes it. Always empty when the deletion was queued (see persons_queued_for_deletion). Contact support if this persists.

Changes

No recorded changes to this operation across all 1 revision of this API.