Managing Personal Data

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

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

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:

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 Project Settings modal under the Management tab in the Mixpanel UI. 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.

Create a Deletion Task

Method: POST

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

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 people profile data, for the users specified by distinct_ids. This deletion job may be canceled until it reaches the STARTED stage.

token
query string parameter
Mixpanel Project Token.
distinct_ids
JSON encoded list
JSON encoded list of distinct_ids or aliases of users to be deleted. All data associated with the values in this list will be deleted. If a value is an alias created in the project, the distinct_id that the alias maps to will be submitted in the deletion, and all data associated with that distinct_id will be deleted as well. Learn more about aliases in our Help Center.

Return Format:

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

Return Key:

task_id
string
Reference ID for the deletion task. It can be used to either get the status of or cancel a deletion task using GET or DELETE.

Example Usage:

$ 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

Method: DELETE

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

Description:

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

token
query string parameter
Mixpanel Project Token.
task_id
URL parameter
Task ID returned from POST.

Return Format:

204 NoContent

or

405 MethodNotAllowed

Return Key:

204
NoContent
Successful Cancelation.
405
MethodNotAllowed
Deletion has already begun.

Example Usage:

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

Check the Status of a Deletion Task

Method: GET

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

Description:

Checks the status of an existing deletion task.

token
query string parameter
Mixpanel Project Token.
task_id
URL parameter
Task ID returned from POST.

Return Format:

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

Return Key:

PENDING
string
Task ID returned from POST.
STAGING
string
The staging process of the deletion task has started. The task can still be canceled during staging.
STARTED
string
The deletion task has started, and cannot be canceled.
SUCCESS
string
The deletion task is complete.
FAILURE
string
The deletion task has failed. Check the original task input parameters and create a new task.
REVOKED
string
The deletion task has been canceled through a DELETE operation.
NOT_FOUND
string
The deletion task cannot be found.
UNKNOWN
string
An error occured while locating the deletion task.

Example Usage:

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

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

Create a Retrieval Task

Method: POST

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

Description:

This will schedule a retrieval job that will collect the events and people 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.

token
query string parameter
Mixpanel Project Token.
distinct_ids
JSON encoded list
JSON encoded list of distinct_ids or aliases of the users whose data is to be retrieved. If a value is an alias created in the project, the distinct_id that the alias maps to will be submitted in the retrieval, and all data associated with that distinct_id will be deleted as well. Learn more about aliases in our Help Center.

Return Format:

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

Return Key:

task_id
string
Reference ID for retrieval task. Can be used to get the status of or cancel a retrieval task using GET or DELETE.

Example Usage:

$ 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

Method: DELETE

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

Description:

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

token
query string parameter
Mixpanel Project Token.
task_id
URL parameter
Task ID returned from POST.

Return Format:

204 NoContent
or
405 MethodNotAllowed

Return Key:

204
NoContent
Successful Cancelation.
405
MethodNotAllowed
Retrieval has already begun.

Example Usage:

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

Check the Status of a Retrieval Task

Method: GET

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

Description:

Checks the status of an existing retrieval task.

token
query string parameter
Mixpanel Project Token.
task_id
URL parameter
Task ID returned from POST.

Return Format:

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

Return Key:

PENDING
string
Task ID returned from POST.
STARTED
string
The retrieval task has started, and cannot be canceled.
SUCCESS
string
The retrieval task is complete.
FAILURE
string
The retrieval task has failed. Check the original task input parameters and create a new task.
REVOKED
string
The retrieval task has been canceled through a DELETE operation.

Example Usage:

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

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