API reference
Data subject requests
GDPR and CCPA erasure, export and suppression. Server API key only.
Erase an end user#
delete/users/{distinctId}
Deletes the end user's events, identity and traits, cohort memberships and decision log rows in this project, then keeps their ID (as a SHA-256 hash) on the suppression list so later data for it is dropped and counted. Deletes run in bounded batches. 200 with a completed receipt; 202 with status: "in_progress" when a very large user needs more time: send the same request again to continue (it resumes the same receipt), or leave it and the daily job finishes it. Idempotent. 120 data subject requests per minute per project.
Parameters
{distinctId}stringrequiredThe end user's distinct id, percent-encoded (encodeURIComponent).
?projectstringrequiredProject id (a UUID; GET /projects lists them). Must belong to the API key's workspace.
curl -X DELETE "https://tughq.com/api/v1/users/user_123?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90" \
-H "Authorization: Bearer $TUG_API_KEY"200 response · JSON
{
"object": "deletion_receipt",
"id": "0d9c8b7a-6f5e-4d3c-8b2a-19f8e7d6c5b4",
"projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
"distinctId": "user_123",
"status": "completed",
"deleted": {
"events": 1842,
"identities": 1,
"cohortMemberships": 3,
"decisions": 12
},
"suppressed": true,
"requestedAt": "2026-11-22T18:02:11.000Z",
"completedAt": "2026-11-22T18:02:12.000Z"
}202 response · JSON
{
"object": "deletion_receipt",
"id": "0d9c8b7a-6f5e-4d3c-8b2a-19f8e7d6c5b4",
"projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
"distinctId": "user_123",
"status": "in_progress",
"deleted": {
"events": 250000,
"identities": 0,
"cohortMemberships": 0,
"decisions": 0
},
"suppressed": true,
"requestedAt": "2026-11-22T18:02:11.000Z",
"completedAt": null
}Export an end user's data#
get/users/{distinctId}/export
Everything Tug stores about the end user in this project: identity and traits, cohort memberships, decision log rows and events. Events are paged oldest first (limit, default 1000, at most 10,000); follow nextCursor while hasMore is true. Other sections come whole on every page.
Parameters
{distinctId}stringrequiredThe end user's distinct id, percent-encoded (encodeURIComponent).
?projectstringrequiredProject id (a UUID; GET /projects lists them). Must belong to the API key's workspace.
?limitintegerEvents per page, 1 to 10000. Default 1000.
?cursorstringnextCursor from the previous page.
curl "https://tughq.com/api/v1/users/user_123/export?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90" \
-H "Authorization: Bearer $TUG_API_KEY"200 response · JSON
{
"object": "user_export",
"projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
"distinctId": "user_123",
"exportedAt": "2026-11-22T18:00:00.000Z",
"suppressed": false,
"identity": {
"traits": {
"plan": "trial"
},
"firstSeenAt": "2026-11-01T09:12:00.000Z",
"lastSeenAt": "2026-11-22T16:41:00.000Z"
},
"cohorts": [
{
"cohortId": "3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f",
"name": "Stalled in setup",
"addedAt": "2026-11-20T07:00:00.000Z"
}
],
"decisions": [
{
"logId": 42,
"recommendationId": "8e1f4a2b-6c3d-4e5f-9a0b-1c2d3e4f5a6b",
"surface": "banner",
"servedAt": "2026-11-21T10:00:00.000Z",
"shownAt": "2026-11-21T10:00:01.000Z",
"clickedAt": null,
"dismissedAt": null,
"convertedAt": null,
"isHoldout": false
}
],
"events": [
{
"id": 90812,
"name": "signup_completed",
"properties": {
"plan": "pro"
},
"occurredAt": "2026-11-22T16:41:00.000Z",
"ingestedAt": "2026-11-22T16:41:01.000Z",
"sessionId": "s_8f2a1c",
"url": "https://app.example.com/signup"
}
],
"hasMore": false,
"nextCursor": null
}Lift a suppression#
delete/suppressions/{distinctId}
Removes the ID from the suppression list an erasure added, so data for it is accepted again (for example, the person signed up again and agreed). Idempotent: removed is false when it wasn't suppressed.
Parameters
{distinctId}stringrequiredThe end user's distinct id, percent-encoded (encodeURIComponent).
?projectstringrequiredProject id (a UUID; GET /projects lists them). Must belong to the API key's workspace.
curl -X DELETE "https://tughq.com/api/v1/suppressions/user_123?project=5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90" \
-H "Authorization: Bearer $TUG_API_KEY"200 response · JSON
{
"object": "suppression",
"projectId": "5b0c7f9e-2d41-4c8a-9a6e-3f1d2b7c8e90",
"distinctId": "user_123",
"removed": true
}