Mixpanel deletion and retrieval APIs are in place to help Mixpanel implementations meet the requirements outlined by the General Data Protection Regulation (GDPR) legislation.
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:
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:
Parameter | Parameter Type | Data Type | Description |
---|---|---|---|
Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel project token. |
distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. |
compliance_type | Body. Passed in JSON blob format. | String | Select CCPA or GDPR. Default is GDPR. |
disclosure_type | Body. Passed in JSON blob format. | String | Only required if compliance_type = CCPA. Can be Data, Categories, or Sources. Default is Data. |
Authorization:
Authorization Type | Pass As | Description |
---|---|---|
Bearer | Body. Passed in JSON blob format. | Your OAuth token for GDPR APIs. |
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:
Name | Type | Description |
---|---|---|
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 occurred while locating the deletion task. |
Parameters:
Parameter | Parameter Type | Type | Description |
---|---|---|---|
Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel project token. |
Task ID | URL. Passed in request URL. | Query String Parameter | The tracking ID shown in the response. |
Authorization:
Authorization Type | Pass As | Description |
---|---|---|
Bearer | Body. Passed in JSON blob format. | Your OAuth token for GDPR APIs. |
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:
Parameters | Parameter Type | Type | Description |
---|---|---|---|
Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel project token. |
distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. |
compliance_type | Body. Passed in JSON blob format. | String | Select CCPA or GDPR. Default is GDPR. |
Authorization:
Authorization Type | Pass As | Description |
---|---|---|
Bearer | Body. Passed in JSON blob format. | Your OAuth token for GDPR APIs. |
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:
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 occurred while locating the deletion task. |
Parameters:
Authorization Type | Pass As | Description |
---|---|---|
Bearer | Body. Passed in JSON blob format. | Your OAuth token for GDPR APIs. |
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:
Name | Type | Description |
---|---|---|
204 | Query String Parameter | Your Mixpanel project token. |
405 | Query String Parameter | Task ID returned from POST. |
Parameters:
Parameter | Token Type | Type | Description |
---|---|---|---|
Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel project token. |
distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. |
Authorization:
Authorization Type | Pass As | Description |
---|---|---|
Bearer | Body. Passed in JSON blob format. | Your OAuth token for GDPR APIs. |
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/
Name | Type | Description |
---|---|---|
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. There is a limit of 2000 distinct_ids per request. |
201 Created
{
"results": {
{"task_id": GUID}
}
}
Return Key:
Name | Type | Description |
---|---|---|
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. |
$ 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
Parameter | Type | Description |
---|---|---|
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:
Value | Description |
---|---|
204 | Successful Cancelation. |
405 | Deletion has already begun. |
$ 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
Parameter | Type | Description |
---|---|---|
token | query string parameter | Mixpanel Project Token. |
task_id | URL parameter | Task ID returned from POST. |
200 OK
{
"results": {
"status": oneOf [
"PENDING",
"STAGING",
"STARTED",
"SUCCESS",
"FAILURE",
"REVOKED",
"NOT_FOUND",
"UNKNOWN",
],
}
}
Return key:
Name | Type | Description |
---|---|---|
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 occurred while locating the deletion task. |
$ 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/
Parameter | Type | Description |
---|---|---|
token | query string parameter | Mixpanel Project Token. |
distinct_id | JSON encoded string | JSON encoded distinct_id or alias of the user whose data to be retrieved. All data associated with the user will 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 retrieved as well. Learn more about aliases in our Help Center. |
201 Created
{
"results": {
{"task_id": GUID}
}
}
Return Key:
Name | Type | Description |
---|---|---|
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. |
$ 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
Parameter | Type | Description |
---|---|---|
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 | Successful Cancelation. |
---|---|
405 | Deletion has already begun. |
$ 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
Name | Type | Description |
---|---|---|
token | query string parameter | Mixpanel Project Token. |
task_id | URL parameter | Task ID returned from POST. |
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. |
$ 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>"}}
Updated 2 months ago