User Profile API

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. In the snippet below, simply replace <api_secret_key> with your project's Secret Key. 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.
rec_id (optional)	Recommendation(s) to be retrieved. 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.
comp_id (optional)	Return computation(s) that might be enabled for this user. It will return a null value if a computation does not exist. Multiple computations can be fetched by separating the comp_ids with commas.

Examples

Get a Recommendation

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&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&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 multiple Computations

Endpoint

https://profile-api.amplitude.com/v1/userprofile?user_id=testUser&comp_id=testCompId,testCompId2

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