The User Profile API serves Amplitude User Profiles, which includes user properties, computed user properties, a list of cohort IDs of cohorts that the user is in, and recommendations.
Authentication
The Profile API currently supports API Key authentication by setting an Authorization header. The authentication used for this API differs from many of the other APIs:
{
"Authorization": "Api-Key <api_secret_key>"
}
Endpoint
https://profile-api.amplitude.com/v1/userprofile
Parameters
| Parameter | Description |
|---|---|
| user_id (optional) | User id (external database id) to be queried, required unless device_id is set. |
| device_id (optional) | Device id (anonymous id) to be queried, required unless user_id is set. |
| get_recs (optional, default=false) | Return a recommendation result for this user. |
| rec_id (optional) | Recommendation(s) to be retrieved, required if get_recs is true. Multiple recommendations can be fetched by separating the rec_ids with commas. |
| rec_type (optional) | Overrides the default experimental control setting and rec_type=model will return modeled recommendations and rec_type=random return random recommendations. Other options may exist in the future. |
| get_amp_props (optional, default=false) | Return a full set of user properties for this user, not including computations |
| get_cohort_ids (optional, default=false) | Return a list of all of the cohort IDs that this user is a part of that have been set up to be tracked. By default cohort membership is not tracked for users for any cohort. |
| get_computations (optional, default=false) | Return a list of all of the computations that are enabled for this user |
| comp_id (optional) | Return a single computation that might be enabled for this user. It will return a null value if it does not exist. If get_computations is true, all values will be fetched, including this one (unless it is archived or deleted). |
Examples
Get a Recommendation
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_recs=true&rec_id=testRecId
Response
{
"userData": {
"recommendations": [
{
"rec_id": "testRecId",
"child_rec_id": "testRecId",
"items": [
"cookie",
"cracker",
"chocolate milk",
"donut",
"croissant"
],
"is_control": false,
"recommendation_source": "model",
"last_updated": 1608670720
}
],
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": null,
"cohort_ids": null
}
}
| Response Parameter | Description |
|---|---|
| rec_id | The recommendation id that was requested. |
| child_rec_id | A more detailed recommendation id that we may use on the backend as part of an internal experiment to improve model performance. In most cases this will be the same as rec_id. |
| items | List of recommendations for this user. |
| is_control | true if this user is part of the control group |
| recommendation_source | Name of the model that was used to generate this recommendation |
| last_updated | Timestamp of when this recommendation was last generated and synced |
Get Multiple Recommendations
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_recs=true&rec_id=testRecId,testRecId2
Response
{
"userData": {
"recommendations": [
{
"rec_id": "testRecId",
"child_rec_id": "testRecId",
"items": [
"cookie",
"cracker",
"chocolate milk",
"donut",
"croissant"
],
"is_control": false,
"recommendation_source": "model",
"last_updated": 1608670720
},
{
"rec_id": "testRecId2",
"child_rec_id": "testRecId2",
"items": [
"bulgogi",
"bibimbap",
"kimchi",
"croffles",
"samgyeopsal"
],
"is_control": false,
"recommendation_source": "model2",
"last_updated": 1608670658
}
],
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": null,
"cohort_ids": null
}
}
Get User Properties
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_amp_props=true
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": {
"library": "http/1.0",
"first_used": "2020-01-13",
"last_used": "2021-03-24",
"number_property": 12,
"boolean_property": true
},
"cohort_ids": null
}
}
Get Cohort IDs
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_cohort_ids=true
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": null,
"cohort_ids": ["cohort1", "cohort3", "cohort7"]
}
}
Get a Single Computation
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&comp_id=testCompId
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": {
"computed-prop-2": "3"
},
"cohort_ids": null
}
}
Get all Computations
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_computations=true
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": {
"computed-prop-1": "5000000.0",
"computed-prop-2": "3"
},
"cohort_ids": null
}
}
Get a Single Prediction Propensity Score
Endpoint
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_propensity=true&propensity_type=score&prediction_id=testPrediction
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": {
"computed-prop-2": "3"
},
"propensity": 0.500001
}
}
Get a Single Prediction Propensity Percentile
https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&get_propensity=true&propensity_type=pct&prediction_id=testPrediction
Response
{
"userData": {
"recommendations": null,
"user_id": "testUser",
"device_id": "ffff-ffff-ffff-ffff",
"amp_props": {
"computed-prop-2": "3"
},
"propensity": 83
}
}
Common Gotchas in Integrating with the User Profile API
Forgetting to use the “is_control” flag
If you don’t serve your default user experience for users with “is_control” = “true”, we won’t be able to measure performance
Not serving a default experience in the case of error responses
There are two common error responses from the API:
- When the user just signed up (< 5 min ago), you will likely get a response:
{"error":"User id and device id not seen before"}
- If a user is < 2 hours old or has been inactive > 90 days, they will have an API response but return
"recommendations": null”
- If we are having maintenance or some kind of issue and return a 500. You can retry or serve the default experience.
In all of these cases, make sure to default to your baseline experience
Authentication errors
- If the Secret Key is correct but User IDs are not of the proper form, or are User IDs from a different project, you will get a response:
{"error":"User id and device id not seen before"}
- If the Secret Key is incorrect, you will get an error (HTTP 401) response:
Invalid Api-Key
- If the Authorization header is missing or malformed you will get an error (HTTP 401) response:
Missing Api-Key in Authorization header
Configuration errors
- If the endpoint or path are incorrect you will get an empty error (HTTP 404) response
- If an insecure http request is sent, it will be redirected to the https endpoint (HTTPS 301) with an HTML body - the Location header contains the proper protocol and URL
301 Moved Permanently
Updated 6 days ago