Data Subject Access Request API

Considerations

• Expect about one file per month per app for which the user has data.
• Each download URL requires the same auth credentials to access.
• Because the API is asynchronous, you must poll to check the status of the request. Refer to the Rate limits section to select the appropriate polling rate.

Asynchronous operation

To support data volume, this API works asynchronously. Getting user data happens in three steps:

1. Make a POST request, which returns a requestId.
2. Make a GET request using the requestId to check the status of the job.
3. After the job finishes, make a GET request to fetch a list of URLs to get the data files from.

Output

Each file is gzipped, and the contents adhere to the following rules:

• One line per event
• Each line is a JSON object
• No order guarantee

Example Output

{"amplitude_id":123456789,"app":12345,"event_time":"2020-02-15 01:00:00.123456","event_type":"first_event","server_upload_time":"2020-02-18 01:00:00.234567"}
{"amplitude_id":123456789,"app":12345,"event_time":"2020-02-15 01:00:11.345678","event_type":"second_event","server_upload_time":"2020-02-18 01:00:11.456789"}
{"amplitude_id":123456789,"app":12345,"event_time":"2020-02-15 01:02:00.123456","event_type":"third_event","server_upload_time":"2020-02-18 01:02:00.234567"}

Rate limits

All DSAR endpoints share a budget of 14.4 K "cost" per hour. POST requests cost 8, and GET requests cost 1. Requests beyond this count get 429 response codes.

For each POST, expect one output file per month per project the user has events for.

For example, if you fetch 13 months of data for a user with data in two projects, expect about 26 files.

To get data for 40 users per hour, you can spend 14400 / 40 = 360 cost per request. Conservatively allocating 52 GETs for output files (twice the computed amount) and 8 for the initial POST, you can poll for the status of the request 360 - 8 - 52 = 300 times.

Given the 3 day SLA for results (4,320 minutes), this allows for checking the status every 4320 / 300 ~= 15 minutes over 3 days. A practical use might be a service that runs every 20 minutes, posting 20 new requests and checking the status of all outstanding requests.

SLAs

• Request jobs complete within 3 days.
• Request result expires in 2 days.
• Users with more than 100k events per month aren't supported.

Example client implementation

base_url = 'https://amplitude.com/api/2/dsar/requests'
payload = {
  "amplitudeId": AMPLITUDE_ID,
  "startDate": "2019-03-01",
  "endDate": "2020-04-01"
}
headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}
auth = HTTPBasicAuth(API_KEY, SECRET_KEY)
r = requests.post(base_url, headers=headers, auth=auth, data=payload)
request_id = r.json().get('requestId')
time.sleep(POLL_DELAY)
while (True):
    r = requests.get(f'{base_url}/{request_id}', auth=auth, headers=headers)
    response = r.json()
    if response.get('status') == 'failed':
        sys.exit(1)
    if response.get('status') == 'done':
        break
    time.sleep(POLL_INTERVAL)
for url in response.get('urls'):
    r = requests.get(url, headers=headers, auth=auth, allow_redirects=True)
    index = url.split('/')[-1]
    filename = f'{AMPLITUDE_ID}-{index}.gz'
    with open(f'{OUTPUT_DIR}/{filename}','wb') as f:
        f.write(r.content)

Create a request for data

curl --location --request POST 'https://amplitude.com/api/2/dsar/requests' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
-u '{org-api-key}:{org-secret-key}' \
--data-raw '{
"userId": "12345",
"startDate": "2020-04-24",
"endDate": "2022-02-20"
}'

Request body

Response

When successful, the call returns a 202 Accepted response and requestId. Use the requestId to poll the job status.

{
    "requestId": 53367
}

Get request status

Poll the data request job to get its status.

curl --location --request GET 'https://amplitude.com/api/2/dsar/requests/{request-id}' \
--header 'Accept: application/json' \
-u '{org-api-key}:{org-secret-key}'

Path variables

Response

Get output files

Download a returned output file.

The download link is valid for two days. Most clients used to send API requests automatically download the data from the S3 link. If your API client doesn't automatically download the file from the link, access it manually using your org API key as the username and your org secret key as the password.

curl --location --request GET 'https://analytics.amplitude.com/api/2/dsar/requests/:request_id/outputs/:output_id' \
-u '{org-api-key}:{org-secret-key}'

Path variables