The User Profile API serves Amplitude user profiles, which include user properties, computed user properties, a list of cohort IDs of cohorts that the user is in, and recommendations.
This API uses an Authorization header. Use your project's Secret Key in the format:
Api-Key SECRET_KEY
For more information, see Find your API Credentials
Region | Endpoint |
---|---|
Standard server | https://profile-api.amplitude.com/v1/userprofile |
Default experiences
is_control=true
, Amplitude can't measure performance.Authentication errors
{"error":"User id and device id not seen before"}
Invalid Api-Key
Missing Api-Key in Authorization header
Configuration errors
Throttling errors
{"error":"Number of requests per minute exceeds system limit. Contact Support if you need this limit raised"}
Parameter |
Description |
---|---|
user_id [^1] |
Optional, but required unless device_id is set. The user ID (external database ID) to be queried. |
device_id [^1] |
Optional, but required unless user_id is set. The device ID (anonymous ID) to be queried. |
get_recs |
Optional. Return a recommendation result for this user. Defaults to false . |
rec_id |
Optional. Recommendations to retrieve, required if get_recs is true. Fetch multiple recommendations by separating the rec_ids with commas. |
rec_type |
Optional. Overrides the default experimental control setting and rec_type=model returns modeled recommendations and rec_type=random returns random recommendations. |
get_amp_props |
Optional. Return a full set of user properties for this user, not including computations. Defaults to false . |
get_cohort_ids |
Optional. Return a list of all the cohort IDs that this user is a part of that have been set up to be tracked. By default cohort membership isn't tracked for users for any cohort. Defaults to false . |
get_computations |
Optional. Return a list of all the computations that are enabled for this user. Defaults to false . |
comp_id |
Optional. Return a single computation that might be enabled for this user. It returns a null value if it doesn't exist. If get_computations is true, all values are fetched, including this one (unless it's archived or deleted). |
Amplitude recommends returning 50 items per request. The maximum allowable is 100 items. Update this value on the Amplitude Recommendation page.
Retrieve a single recommendation by ID.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example retrieves the recommendation with ID
Example: Get a specific recommendation
98765
for the user with ID 12345
.
1{ 2 "userData":{ 3 "recommendations":[ 4 { 5 "rec_id":"98765", 6 "child_rec_id":"98765", 7 "items":[ 8 "cookie", 9 "cracker",10 "chocolate milk",11 "donut",12 "croissant"13 ],14 "is_control":false,15 "recommendation_source":"model",16 "last_updated":160867072017 }18 ],19 "user_id":"12345",20 "device_id":"ffff-ffff-ffff-ffff",21 "amp_props":null,22 "cohort_ids":null23 }24}
Response Parameter | Description |
---|---|
rec_id |
The requested recommendation ID. |
child_rec_id |
A more detailed recommendation ID that Amplitude may use as part of an internal experiment to improve model performance. This usually 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 used to generate this recommendation. |
last_updated |
Timestamp of when this recommendation was last generated and synced. |
Amplitude recommends returning 50 items per request. The maximum allowable is 100 items. Update this value on the Amplitude Recommendation page.
Retrieves multiple recommendations for a user.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId,testRecID2' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId,testRecId2 HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example retrieves the recommendation with ID
Example: Get multiple recommendations
98765
and 56789
for the user with ID 12345
.
1{ 2 "userData": { 3 "recommendations": [ 4 { 5 "rec_id": "testRecId", 6 "child_rec_id": "testRecId", 7 "items": [ 8 "cookie", 9 "cracker",10 "chocolate milk",11 "donut",12 "croissant"13 ],14 "is_control": false,15 "recommendation_source": "model",16 "last_updated": 160867072017 },18 {19 "rec_id": "testRecId2",20 "child_rec_id": "testRecId2",21 "items": [22 "bulgogi",23 "bibimbap",24 "kimchi",25 "croffles",26 "samgyeopsal"27 ],28 "is_control": false,29 "recommendation_source": "model2",30 "last_updated": 160867065831 }32 ],33 "user_id": "12345",34 "device_id": "ffff-ffff-ffff-ffff",35 "amp_props": null,36 "cohort_ids": null37 }38}
Retrieves the user's properties.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_amp_props=true' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_amp_props=true HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example retrieves the user properties for the user with ID
Example: Get user properties by user ID
12345
.
1{ 2 "userData": { 3 "recommendations": null, 4 "user_id": "12345", 5 "device_id": "ffff-ffff-ffff-ffff", 6 "amp_props": { 7 "library": "http/1.0", 8 "first_used": "2020-01-13", 9 "last_used": "2021-03-24",10 "number_property": 12,11 "boolean_property": true12 },13 "cohort_ids": null14 }15}
Retrieves a user's cohort IDs.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_cohort_ids=true' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_cohort_ids=true HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example gets cohort IDs for user ID
Example:
12345
1{2 "userData": {3 "recommendations": null,4 "user_id": "testUser",5 "device_id": "ffff-ffff-ffff-ffff",6 "amp_props": null,7 "cohort_ids": ["cohort1", "cohort3", "cohort7"]8 }9}
Computations convert events into a new user property you can use to segment your users.
Computations work by transforming an event or event property into a computed user property. You can use the computed property as a configurable filter in any Amplitude chart for analysis, or as a personalization tool by syncing it to an external destination.
Retrieve all computations for a user.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?get_computations=true&user_id=USER_ID' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?get_computations=true&user_id=USER_ID HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example retrieves all computations for user ID
Example: Get all computations for a user
12345
.
1{ 2 "userData": { 3 "recommendations": null, 4 "user_id": "testUser", 5 "device_id": "ffff-ffff-ffff-ffff", 6 "amp_props": { 7 "computed-prop-1": "5000000.0", 8 "computed-prop-2": "3" 9 },10 "cohort_ids": null11 }12}
Retrieves a single or multiple computation by ID. Navigate to the computation in Audiences to find and copy the ID at the end of the URL. For example, t14bqib
is the ID in https://app.amplitude.com/audiences/org_name_00000/computations/t14bqib/
To fetch multiple comp_id
, separate comp_id
by comma(,). For example: comp_id=id1,id2
. Responses for multiple comp_id IDs are in the amp_props
field.
Retrieve a computation for a user by ID.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_computations=true&comp_id=COMP_ID' \2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_computations=true&comp_id=COMP_ID HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example retrieves the computation with ID
Example: Get a computation by ID for a specific user
t14bqib
for user ID 12345
.
1{ 2 "userData": { 3 "recommendations": null, 4 "user_id": "testUser", 5 "device_id": "ffff-ffff-ffff-ffff", 6 "amp_props": { 7 "computed-prop-2": "3" 8 }, 9 "cohort_ids": null10 }11}
When you create a prediction in Amplitude Audiences, you can sync the prediction score to the Profile API. A prediction propensity is the probability that a user performs a predicted action.
To fetch a user's prediction propensity, send a request that includes a prediction_id
and propensity_type
. The propensity type can be either the raw score (score
) or a percentile (pct
).
Percentile is useful to understand users in comparison to each other. For example, is this user in the 80% of users likely to do an action?
Score is the raw propensity score.
Find the prediction_id
by navigating to the prediction in the Audiences web app and copying the ID at the end of the URL. The ID is 0x10x
in this example:
recommend.amplitude.com/0000/predictions/0x10x
To fetch multiple prediction_id
, separate prediction_id
by comma(,). For example: prediction_id=id1,id2
. Responses for multiple prediction_id
IDs are in the propensities
field.
1curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_propensity=true&prediction_id=PREDICTION_ID&propensity_type=PROPENSITY_TYPE'2--header 'Authorization: Api-Key <SECRET KEY>'
1GET /v1/userprofile?user_id=USER_ID&get_propensity=&prediction_id=PREDICTION_ID&propensity_type=PROPENSITY_TYPE HTTP/1.12Host: profile-api.amplitude.com3Authorization: Api-Key <SECRET KEY>
This example requests a propensity score for prediction ID
Response:
Example: Propensity score
0x10x
for the user ID 12345
.
This example requests a propensity percentage for prediction ID
Response:
Example: Propensity percentage
0x10x
for the user ID 12345
.
This example requests a propensity percentage for prediction ID
Response:
Example: Propensity score with multiple prediction IDs
0x10x
and 0x11x
for the user ID 12345
.
Thanks for your feedback!
May 21st, 2024
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.