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.

Auth: server API key.

Parameters

  • {distinctId}stringrequired

    The end user's distinct id, percent-encoded (encodeURIComponent).

  • ?projectstringrequired

    Project 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
}

Errors: invalid_request (400), server_key_required (401), invalid_api_key (401), project_not_found (404), rate_limited (429), internal_error (500), service_unavailable (503).

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.

Auth: server API key.

Parameters

  • {distinctId}stringrequired

    The end user's distinct id, percent-encoded (encodeURIComponent).

  • ?projectstringrequired

    Project id (a UUID; GET /projects lists them). Must belong to the API key's workspace.

  • ?limitinteger

    Events per page, 1 to 10000. Default 1000.

  • ?cursorstring

    nextCursor 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
}

Errors: invalid_request (400), server_key_required (401), invalid_api_key (401), project_not_found (404), rate_limited (429), internal_error (500), service_unavailable (503).

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.

Auth: server API key.

Parameters

  • {distinctId}stringrequired

    The end user's distinct id, percent-encoded (encodeURIComponent).

  • ?projectstringrequired

    Project 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
}

Errors: invalid_request (400), server_key_required (401), invalid_api_key (401), project_not_found (404), rate_limited (429), internal_error (500), service_unavailable (503).

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides