# User Profile API

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

> **Warning:** Unavailable in EU Region
>
> This API isn't supported for customers in Amplitude's EU data processing region.

## Considerations

> **Warning:** 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

| 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. `rec_type=model` returns modeled recommendations; `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 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_computations` | _Optional_. Return a list of computations enabled for this user. Defaults to `false`. |
| `comp_id` | _Optional_. 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get a specific recommendation

This example retrieves the recommendation with ID `98765` for the user with ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_recs=true&rec_id=98765' \
--header 'Authorization: Api-Key 1234567890'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_recs=true&rec_id=98765 HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 1234567890
```

### 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 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. 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. |

## 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId,testRecId2 HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get multiple recommendations

This example retrieves the recommendation with ID `98765` and `56789` for the user with ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_recs=true&rec_id=98765,56789' \
--header 'Authorization: Api-Key 1234567890'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_recs=true&rec_id=98765,56789 HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 1234567890
```

### 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_amp_props=true HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get user properties by user ID

This example retrieves the user properties for the user with ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_amp_props=true' \
--header 'Authorization: Api-Key 1234567890'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_amp_props=true HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 1234567890
```

### 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](https://amplitude.com/docs/data/destination-catalog/movable-ink-profile-api).

> **Note:** Profile API limit
>
> Amplitude limits cohort syncs with the Profile API to 10 million users or fewer.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_cohort_ids=true HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get cohort IDs for a user

This example gets cohort IDs for user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_cohort_ids=true' \
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_cohort_ids=true HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

### 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?get_computations=true&user_id=USER_ID HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get all computations for a user

This example retrieves all computations for user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_computations=true'
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?get_computations=true&user_id=1234 HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

```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/`.

> **Note:** 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_computations=true&comp_id=COMP_ID HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Get a computation by ID for a specific user

This example retrieves the computation with ID `t14bqib` for user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_computations=true&comp_id=t14bqib'
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?get_computations=true&user_id=1234&comp_id=t14bqib HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

```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 type | Description |
| --- | --- |
| `score` | The raw propensity score. |
| `pct` | The 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`

> **Note:** 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.

#### cURL

```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>'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=USER_ID&get_propensity=&prediction_id=PREDICTION_ID&propensity_type=PROPENSITY_TYPE HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key <SECRET KEY>
```

#### Example: Propensity score

This example requests a propensity score for prediction ID `0x10x` for the user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_propensity=true&prediction_id=0x10x&propensity_type=score'
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_propensity=&prediction_id=0x10x&propensity_type=score HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

Response:

```json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": null,
    "amp_props": null,
    "cohort_ids": null,
    "propensity": 0.500001,
    "propensities": [
        {
            "prop": 0.500001,
            "pred_id": "0x10x",
            "prop_type": "score"
        }
    ]
  }
}
```

#### Example: Propensity percentage

This example requests a propensity percentage for prediction ID `0x10x` for the user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_propensity=true&prediction_id=0x10x&propensity_type=pct'
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_propensity=&prediction_id=0x10x&propensity_type=pct HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

Response:

```json
{
    "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": null,
    "amp_props": null,
    "cohort_ids": null,
    "propensity": 83,
    "propensities": [
        {
            "prop": 83,
            "pred_id": "0x10x",
            "prop_type": "pct"
        }
    ]
    }
}
```

#### Example: Propensity score with multiple prediction IDs

This example requests a propensity percentage for prediction ID `0x10x` and `0x11x` for the user ID `12345`.

#### cURL

```bash
curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=12345&get_propensity=true&prediction_id=0x10x,0x11x&propensity_type=pct'
--header 'Authorization: Api-Key 123456789'
```

#### HTTP

```bash
GET /v1/userprofile?user_id=12345&get_propensity=&prediction_id=0x10x,0x11x&propensity_type=pct HTTP/1.1
Host: profile-api.amplitude.com
Authorization: Api-Key 123456789
```

Response:

```json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": null,
    "amp_props": null,
    "cohort_ids": null,
    "propensity": null,
    "propensities": [
        {
            "prop": 83,
            "pred_id": "0x10x",
            "prop_type": "score"
        },
        {
            "prop": 85,
            "pred_id": "0x11x",
            "prop_type": "score"
        }
    ]
  }
}
```