Mixpanel deletion and retrieval APIs are in place to help Mixpanel implementations meet the requirements outlined by the General Data Protection Regulation (GDPR) legislation.

📘

NOTE

The APIs described in this document are beta versions and are therefore subject to change.

📘

GDPR Request Rate Limits

You can batch up to 2000 distinct IDs per request. Request rates are limited for GDPR API requests.

User Opt-Out

While the following API can be used to delete or retrieve personal data as outlined by the GPDR, it is important to also opt users out of subsequent tracking. If tracking using a client-side Mixpanel library, you can opt users out of tracking using Mixpanel's opt-out methods. These are available in the following client-side libraries:

• JavaScript
• iOS - Objective-C
• iOS - Swift
• Android

See Mixpanel’s Managing Personal Information guide for more information on best practices when handling personal information in Mixpanel.

Authentication

Authentication occurs via a user-specific OAuth token with a scope that only includes the following deletion and retrieval APIs. Users can retrieve this token from their Account Settings by selecting their initials in the top right of Mixpanel and selecting Profile & Preferences, and then the Data & Privacy tab. The OAuth token has a one year expiry. It should be passed in the Authentication header. Users are eligible to generate an OAuth token if they are the project owner, or if they are a project owner or admin of a project that supports team member roles.

GDPR and CCPA API Version 3

The following retrieval and deletion API calls are updated for version 3 and are made for GDPR and CCPA compliance.

Create Retrieval

Request Type: POST
Description: Creates a data retrieval job.
Endpoint: https://mixpanel.com/api/app/data-retrievals/v3.0/?token=<your_project_token>
Parameters:

Authorization:

Example Request:
curl “https://mixpanel.com/api/app/data-retrievals/v3.0/?token=591b3354bb2bdd96f72f23bf56911673” -H “Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc” -d '{"compliance_type":"CCPA","disclosure_type": "Data", "distinct_ids":["1"]}'

Example Return:
{"status":"ok","results":[{"status":"PENDING", "disclosure_type":"DATA", "date_requested":"2020-03-09T22:28:55.078315", "tracking_id":"1583792934719392965", "project_id":1978118, "compliance_type":"ccpa", "destination_url":null, "requesting_user":"[email protected]", "distinct_id_count":1}]}

Check Status of Retrieval

Request Type: GET

Description: Checks the status of a data retrieval job.

Endpoint: https://mixpanel.com/api/app/data-retrievals/v3.0/<tracking_id>?token=<your_project_token>

Return Format:
200 OK { "results": { "status": oneOf [ "PENDING", "STAGING", "STARTED", "SUCCESS", "FAILURE", "REVOKED", "NOT_FOUND", "UNKNOWN", ], } }

Return Key:

Parameters:

Authorization:

Example Request:
curl “https://mixpanel.com/api/app/data-retrievals/v3.0/1583958896131033662/?token=591b3354bb2bdd96f72f23bf56911673” -H “Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc”

Example Return:
{"status": "ok", "results": {"status": "PENDING", "result": "", "distinct_ids": ["1"]}}

Create a Deletion Task

Request Type: POST

Description: Creates a task that specifies a list of users in a particular project to delete. This will schedule a deletion job that will delete all data, including events and user profile data, for the users specified by distinct_ids. This deletion job may be canceled until it reaches the STARTED stage. A task can take up to 7 days to complete.

Endpoint: https://mixpanel.com/api/app/data-deletions/v3.0/?token=<your_project_token>

Parameters:

Authorization:

Example Request:
curl “https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673” -H “Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc” -d '{"compliance_type":"CCPA", "distinct_ids":["1"]}'

Example Return:
{"status":"ok","results":[{"status":"PENDING", "disclosure_type":"DATA", "date_requested":"2020-03-09T22:28:55.078315", "tracking_id":"1583792934719392965", "project_id":1978118, "compliance_type":"ccpa", "destination_url":null, "requesting_user":"[email protected]", "distinct_id_count":1}]}

Check Status of a Deletion Task

Request Type: GET

Description: Checks the status of an existing deletion task.

Endpoint: https://mixpanel.com/api/app/data-deletions/v3.0/<tracking_id>?token=<your_project_token>

Return Format:
"results": { "status": //You will get one of the following returns oneOf [ "PENDING", "STAGING", "STARTED", "SUCCESS", "FAILURE", "REVOKED", "NOT_FOUND", "UNKNOWN", ], } }

Return Key:

Parameters:

Example Request:
curl “https://mixpanel.com/api/app/data-deletions/v3.0/35bd8477-f71f-4088-af55-c88a6fb4ad4b/?token=591b3354bb2bdd96f72f23bf56911674” -H “Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc” -d '{"distinct_ids":["1"]}'

Example Return:
{"status": "ok", "results": {"status": "PENDING", "result": "", "distinct_ids": ["1"]}}

Cancel Deletion

Request Type: DELETE

Description: Cancels an existing deletion task. Deletion jobs can be canceled until the STARTED stage initiates.

Endpoint: https://mixpanel.com/api/app/data-deletions/v3.0/?token=<your_project_token>

Return Format: 204 NoContent or 405 MethodNotAllowed

Return Key:

Parameters:

Authorization:

Example Request:
curl “https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673” -H “Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc” -d '{"distinct_ids":["1"]}'

Example Return:
{"status": "ok", "results": {"task_id": "35bd8477-f71f-4088-af55-c88a6fb4ad4a"}}

GDPR API Version 2

The following syntax applies only to Version 2 of the GDPR and CCPA API.

Create a Deletion Task

**Request Type: **POST

Creates a task that specifies a list of users in a particular project to delete. This will schedule a deletion job that will delete all data, including events and user profile data, for the users specified by distinct_ids. This deletion job may be canceled until it reaches the STARTED stage. A task can take up to 7 days to complete.

URI: https://mixpanel.com/api/app/data-deletions/v2.0/

201 Created
{
        "results": {
        {"task_id": GUID}
    }
}

Return Key:

$ curl https://mixpanel.com/api/app/data-deletions/v2.0/?token=<your_project_token> \
    -H 'Authorization: Bearer <your_oauth_token>' \
    -H 'Content-Type: application/json' \
    -d '{"distinct_ids":["hello", "world"]}' 

{"results": {"task_id": "f5d3a418-a3d1-4177-8104-19bb5579af3a"}}

Cancel a Deletion Task

**Request Type: **DELETE

Cancels an existing deletion task. Deletion jobs can be canceled until the STARTED stage initiates.

URI: https://mixpanel.com/api/app/data-deletions/v2.0/task_id

Return Format: 204 NoContent or 405 MethodNotAllowed

Return Key:

$ curl https://mixpanel.com/api/app/data-deletions/v2.0/task_id?token=<your_project_token> \
    -H 'Authorization: Bearer <your_oauth_token>' \
    -X DELETE 
$

Check the Status of a Deletion Task

**Request Type: **GET

Checks the status of an existing deletion task.

URI: https://mixpanel.com/api/app/data-deletions/v2.0/task_id

200 OK
{    
    "results": {
         "status":  oneOf [
                         "PENDING",
                         "STAGING",
                         "STARTED",
                         "SUCCESS",
                         "FAILURE",
                         "REVOKED",
                         "NOT_FOUND",
                         "UNKNOWN",
          ],
     }
}

Return key:

$ curl https://mixpanel.com/api/app/data-deletions/v2.0/task_id/?token=<your_project_token> \
    -H 'Authorization: Bearer <oauth token>' 

{"results": {"status": "PENDING"}}

Create a Retrieval Task

**Request Type: **POST

This will schedule a retrieval job that will collect the events and user profile data for the users specified by the distinct_id. This job may be canceled until it reaches a terminal state (FAILURE or SUCCESS). The output of a successful job will be a signed URL to a zip file encrypted with the project’s API secret. A task can take up to 7 days to complete.

URI:https://mixpanel.com/api/app/data-retrievals/v2.0/

201 Created
{
        "results": {
        {"task_id": GUID}
    }
}

Return Key:

$ curl https://mixpanel.com/api/app/data-retrievals/v2.0?token=<your_project_token> \
    -H 'Authorization: Bearer <your_oauth_token>' \
    -H 'Content-Type: application/json' \
    -d '{"distinct_id":"2"}'

{"results": {"task_id": "771627de-59f5-4ae4-a0ee-c8dcc1a150c8"}}

Cancel a Retrieval Task

**Request Type: **DELETE

Cancels an existing retrieval task. Retrieval jobs can be canceled until the STARTED stage initiates.

URI: https://mixpanel.com/api/app/data-retrievals/v2.0/task_id

Return Format: 204 NoContent or 405 MethodNotAllowed

Return Key:

$ curl https://mixpanel.com/api/app/data-retrievals/v2.0/task_id?token=<your_project_token> \
    -H 'Authorization: Bearer <your_oauth_token>' \
    -X DELETE 
$

Check the Status of a Retrieval Task

**Request Type: **GET

Checks the status of an existing retrieval task.

URI: https://mixpanel.com/api/app/data-retrievals/v2.0/task_id

200 OK
{    
    "results": {
         "status":  oneOf [
                         "PENDING",
                         "STAGING",
                         "STARTED",
                         "SUCCESS",
                         "FAILURE",
                         
          ],
     }
}

Return Key:

$ curl https://mixpanel.com/api/app/data-retrievals/v2.0/task_id/?token=<your_project_token> \
    -H 'Authorization: Bearer <oauth token>'

{"results": {"status": "SUCCESS", "result": "https://storage.googleapis.com/<blob-path>?<blob-signature>"}}