Amplitude Profiles API

openapi: 3.2.0
info:
  title: Amplitude User Profile Profiles API
  description: The Amplitude User Profile API serves user profiles that include user properties, computed user properties, a list of cohort IDs the user belongs to, and personalized recommendations. It enables real-time access to enriched user data for powering personalization engines, in-app experiences, and targeted content delivery. This API is particularly useful for retrieving recommendation results generated by Amplitude's machine learning models.
  version: '1'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://profile-api.amplitude.com
  description: Amplitude Profile API Server
security:
- apiKeyAuth: []
tags:
- name: Profiles
  description: User profile retrieval operations
paths:
  /v1/userprofile:
    get:
      operationId: getUserProfile
      summary: Amplitude Get a User Profile
      description: Retrieve the profile for a specific user including user properties, computed properties, cohort memberships, and personalized recommendations. The response includes all enriched data Amplitude has computed for the user.
      tags:
      - Profiles
      parameters:
      - name: user_id
        in: query
        required: true
        description: The user_id of the user whose profile to retrieve.
        schema:
          type: string
      - name: comp_id
        in: query
        description: The computed property ID or recommendation ID to retrieve specific computed results for the user.
        schema:
          type: integer
      - name: get_recs
        in: query
        description: When true, include personalized recommendations in the response.
        schema:
          type: boolean
          default: false
      - name: rec_id
        in: query
        description: The recommendation model ID to retrieve specific recommendation results.
        schema:
          type: string
      - name: rec_type
        in: query
        description: The type of recommendation to retrieve.
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of recommendation results to return.
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
              examples:
                getUserProfile200Example:
                  summary: Default getUserProfile 200 response
                  x-microcks-default: true
                  value:
                    userData:
                      user_id: {}
                      user_properties: {}
                      computed_properties: {}
                      cohort_ids: {}
                      recommendations: {}
                      amplitude_id: {}
        '400':
          description: Bad request - missing user_id
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: User not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    UserData:
      type: object
      properties:
        user_id:
          type: string
          description: The user's user_id.
        user_properties:
          type: object
          description: A dictionary of the user's properties as set via the Identify API or SDK.
          additionalProperties: true
        computed_properties:
          type: object
          description: A dictionary of computed properties calculated by Amplitude for the user.
          additionalProperties: true
        cohort_ids:
          type: array
          description: Array of cohort IDs the user is a member of.
          items:
            type: string
        recommendations:
          type: array
          description: Array of personalized recommendation results for the user. Only included when get_recs is true.
          items:
            $ref: '#/components/schemas/Recommendation'
        amplitude_id:
          type: integer
          format: int64
          description: The Amplitude internal ID for the user.
    Recommendation:
      type: object
      properties:
        rec_id:
          type: string
          description: The recommendation model ID.
        child_ids:
          type: array
          description: Array of recommended item IDs.
          items:
            type: string
        is_control:
          type: boolean
          description: Whether the user is in the control group for this recommendation model.
        recommendation_type:
          type: string
          description: The type of recommendation model.
        title:
          type: string
          description: The title of the recommendation.
    UserProfileResponse:
      type: object
      properties:
        userData:
          $ref: '#/components/schemas/UserData'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Pass your deployment key in the Authorization header with the prefix Api-Key, for example Api-Key YOUR_API_KEY.
externalDocs:
  description: Amplitude User Profile API Documentation
  url: https://amplitude.com/docs/apis/analytics/user-profile