Skip to main content

Amplitude - User Profiles

Access Amplitude's User Profile API to retrieve user properties, cohort memberships, and personalized recommendations. This connector is designed for server-side personalization and accessing detailed user-level data.

When to Use This Connector​

Use this connector when you need to:

  • Retrieve complete user profiles with all properties
  • Check which cohorts a user belongs to
  • Get personalized recommendations for users
  • Build personalized experiences based on user data
  • Access user computations and predictions

For sending events or querying analytics, see the Amplitude Overview for other connector options.

Important Limitations​

US Region Only: The User Profile API is only available for projects in Amplitude's US region. If your project is in the EU region, this connector will not work.

Server-Side Only: This connector should only be used server-side to avoid exposing your secret key.

Authentication​

This connector uses Secret Key authentication in the Authorization header.

  • Credential Format: Just your secret key
  • Example: sk_def456uvw012

Security Warning: Never expose your secret key in client-side code or public repositories.

Setting up Authentication​

Step 1: Get Your Secret Key​

  1. Go to amplitude.com and log in to your account
  2. Click on Settings (gear icon) in the top right corner
  3. Scroll to Connections → API Keys
  4. Click Generate API Key or select an existing one
  5. Click Create Secret Key (if you haven't already)
  6. Copy the Secret Key

Important: The secret key is only shown once when generated. Make sure to copy it immediately.

Step 2: Verify Your Region​

Check that your Amplitude project is in the US region. This connector will not work for EU region projects.

Step 3: Configure in Webrix/MCP​

Enter only your secret key (not the API key):

sk_def456uvw012

Note: You only need the secret key for this connector, not the API key.

Available Tools​

This connector provides 3 tools for accessing user profile data:

1. Get User Profile​

Fetch complete user profile including properties, cohort memberships, and recommendations. Use this to retrieve all data about a specific user for personalization or analytics.

Parameters:

  • user_id - The user ID to query (required)
  • get_recs - Whether to include recommendations (optional)
  • rec_id - Specific recommendation ID to retrieve (optional)
  • rec_type - Type of recommendation, e.g., 'Amplify' (optional)

2. Get User Cohorts​

Get all cohorts that a specific user belongs to. Use this to check user segmentation and group membership for targeting, personalization, or feature flags.

Parameters:

  • user_id - The user ID to query (required)

Returns: Array of cohort IDs that the user belongs to

3. Get User Recommendations​

Get personalized recommendations for a specific user. Use this to retrieve AI-powered recommendations for content, products, or actions to show to the user.

Requirements: Requires Amplitude Recommend or Amplify

Parameters:

  • user_id - The user ID to query (required)
  • rec_id - Recommendation ID from your Amplitude configuration (required)
  • rec_type - Type of recommendation, e.g., 'Amplify' (optional)

Returns: Array of recommended items for the user

Troubleshooting​

"User Profile API is not available"​

Cause: Your Amplitude project is in the EU region, or User Profile API is not included in your plan.

Solution:

  • User Profile API is only available for US region projects
  • Check your Amplitude plan to ensure User Profile API is included
  • For EU projects, use the Analytics connector for cohort data instead

"Invalid Api-Key"​

Cause: The secret key is incorrect or has been regenerated.

Solution:

  • Verify you copied the complete secret key from Amplitude
  • Ensure there are no extra spaces or line breaks
  • Make sure you're using the secret key (not the API key)
  • Check that the secret key hasn't been regenerated

"User id and device id not seen before"​

Cause: The user ID is not recognized in your Amplitude project, or you're using credentials from a different project.

Solution:

  • Verify the user ID exists in your Amplitude project
  • Check that you're using the secret key from the correct project
  • Make sure users have been tracked with this ID before querying

"Missing Api-Key in Authorization header"​

Cause: Authentication is not being sent correctly.

Solution:

  • This is automatically handled by the connector
  • Verify your secret key is correctly configured in the connector settings
  • Check that you entered only the secret key (not API key)

Rate Limits​

Amplitude has rate limits for the User Profile API:

  • 600 requests per minute per organization

Solution:

  • Implement rate limiting in your application
  • Use exponential backoff for rate limit errors (429 status)
  • Cache user profile data when appropriate
  • For batch use cases, pace your requests to stay under the limit

Best Practices​

  1. Server-Side Only: Never expose your secret key in client-side code
  2. Cache Results: Cache user profile data to reduce API calls
  3. Batch Requests: When fetching profiles for multiple users, pace requests to avoid rate limits
  4. Error Handling: Serve a default experience if the API is unavailable or returns an error
  5. Control Groups: Respect is_control flag in recommendation responses
  6. Cohort Syncing: Sync cohorts to Profile API first using the Amplitude dashboard
  7. User ID Format: Ensure user IDs match the format used in your event tracking

Use Cases​

Personalization​

Get User Profile → Get User Recommendations
→ Display personalized content based on recommendations

Feature Flags​

Get User Cohorts
→ Check if user is in "Beta Features" cohort
→ Enable/disable features accordingly

User Support​

Get User Profile
→ Retrieve all user properties and cohorts
→ Provide context for support team

A/B Testing​

Get User Recommendations
→ Check is_control flag
→ Serve experiment or control experience

Additional Resources​