On this page

User Profile API

Unavailable in EU Region

This API isn't supported for customers in Amplitude's EU data processing region.

Considerations

Server-side API

Amplitude recommends that you use the User Profile API server-side only. Calling the API from the client may expose your project's secret key.

Default experiences

  • If you don't serve your default user experience for users with is_control=true, Amplitude can't measure performance.
  • Serve a default experience in case of an error.
  • If Amplitude is unavailable and returns a 500 response, you can retry or serve the default experience.

Authentication errors

  • If the secret key is correct but user IDs are improperly formatted, or are user IDs from a different project, the API returns this error: {"error":"User id and device id not seen before"}
  • If the secret key is wrong, the API returns an HTTP 401 response: Invalid Api-Key
  • If the authorization header is missing or malformed, the API returns an HTTP 401 response: Missing Api-Key in Authorization header

Configuration errors

  • If the endpoint or path are wrong, the API returns an empty error (HTTP 404) response.
  • If you send an insecure HTTP request, the API redirects to the HTTPS endpoint (HTTP 301) with an HTML body. The Location header contains the correct protocol and URL.

Throttling errors

  • Amplitude orgs have a limit of 600 API requests per minute across all endpoints. If you exceed this limit, contact Support with the use case and required limit.
    • {"error":"Number of requests per minute exceeds system limit. Contact Support if you need this limit raised"}
  • For batch recommendation use cases, rate limit your requests to stay within this limit.

Request Parameters

ParameterDescription
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_recsOptional. Return a recommendation result for this user. Defaults to false.
rec_idOptional. Recommendations to retrieve, required if get_recs is true. Fetch multiple recommendations by separating the rec_ids with commas.
rec_typeOptional. Overrides the default experimental control setting. rec_type=model returns modeled recommendations; rec_type=random returns random recommendations.
get_amp_propsOptional. Return a full set of user properties for this user, not including computations. Defaults to false.
get_cohort_idsOptional. Return a list of cohort IDs that this user belongs to and that are configured for tracking. Cohort membership isn't tracked by default. Defaults to false. The API only returns cohorts synced to Profile API.
get_computationsOptional. Return a list of computations enabled for this user. Defaults to false.
comp_idOptional. Return a single computation that might be enabled for this user. Returns a null value if the computation doesn't exist. When get_computations is true, the API fetches all values, including this one, unless the computation is archived or deleted.

Get a recommendation

Retrieve a single recommendation by ID. Amplitude recommends returning 50 items per request. The maximum is 100 items. Update this value on the Amplitude Recommendation page.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId' \
--header 'Authorization: Api-Key <SECRET KEY>'

Response

json
{
  "userData":{
    "recommendations":[
      {
        "rec_id":"98765",
        "child_rec_id":"98765",
        "items":[
          "cookie",
          "cracker",
          "chocolate milk",
          "donut",
          "croissant"
        ],
        "is_control":false,
        "recommendation_source":"model",
        "last_updated":1608670720
      }
    ],
    "user_id":"12345",
    "device_id":"ffff-ffff-ffff-ffff",
    "amp_props":null,
    "cohort_ids":null
  }
}
Response ParameterDescription
rec_idThe requested recommendation ID.
child_rec_idA more detailed recommendation ID that Amplitude may use as part of an internal experiment to improve model performance. Usually the same as rec_id.
itemsList of recommendations for this user.
is_controltrue if this user is part of the control group.
recommendation_sourceName of the model used to generate this recommendation.
last_updatedTimestamp of when this recommendation was last generated and synced.

Get multiple recommendations

Retrieve multiple recommendations for a user. Amplitude recommends returning 50 items per request. The maximum is 100 items. Update this value on the Amplitude Recommendation page.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId,testRecID2' \
--header 'Authorization: Api-Key <SECRET KEY>'

Response

json
{
  "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": "12345",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": null
  }
}

Get user properties

Retrieve the user's properties.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_amp_props=true' \
--header 'Authorization: Api-Key <SECRET KEY>'

Response

json
{
  "userData": {
    "recommendations": null,
    "user_id": "12345",
    "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

Retrieve a user's cohort IDs. Before you use get cohort IDs, sync your cohorts using the User Profile API.

Profile API limit

Amplitude limits cohort syncs with the Profile API to 10 million users or fewer.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_cohort_ids=true' \
--header 'Authorization: Api-Key <SECRET KEY>'

Response

json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": ["cohort1", "cohort3", "cohort7"]
  }
}

Get all computations

Computations transform an event or event property into a computed user property you can use to segment users. 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.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?get_computations=true&user_id=USER_ID' \
--header 'Authorization: Api-Key <SECRET KEY>'

json
{
  "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 computation by ID

Retrieve one or more computations 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/.

Get multiple computations

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.

bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_computations=true&comp_id=COMP_ID' \
--header 'Authorization: Api-Key <SECRET KEY>'

json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-2": "3"
    },
    "cohort_ids": null
  }
}

Get single or multiple prediction propensity

When you create a prediction in Amplitude Activation, 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).

Propensity typeDescription
scoreThe raw propensity score.
pctThe user's percentile compared to other users. Useful for ranking users, such as identifying the top 20% most likely to perform an action.

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

Get multiple computations

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.

bash
curl --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'
--header 'Authorization: Api-Key <SECRET KEY>'

Was this helpful?