Segment Profile API

openapi: 3.1.0
info:
  title: Segment Profile API
  description: >-
    The Segment Profile API provides endpoints to read user-level and
    account-level customer data from Segment Unify. Developers can
    query the entire user or account object programmatically, including
    external IDs, traits, and events that make up a user's journey.
    The API uses basic authentication and typically delivers p95
    response times under 200ms for the traits endpoint. It is commonly
    used for real-time personalization and customer data retrieval.
  version: '1.0.0'
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
externalDocs:
  description: Segment Profile API Documentation
  url: https://segment.com/docs/unify/profile-api/
servers:
  - url: https://profiles.segment.com/v1/spaces/{spaceId}
    description: Production Server
    variables:
      spaceId:
        description: >-
          The ID of the Segment Unify space.
        default: ''
tags:
  - name: Events
    description: >-
      Operations for retrieving events associated with a user
      or account profile.
  - name: External IDs
    description: >-
      Operations for retrieving external identifiers linked to
      a user or account profile.
  - name: Links
    description: >-
      Operations for retrieving linked profiles and relationships.
  - name: Profiles
    description: >-
      Operations for retrieving user and account profile data from
      Segment Unify.
  - name: Traits
    description: >-
      Operations for retrieving computed and custom traits for
      user and account profiles.
security:
  - basicAuth: []
paths:
  /collections/users/profiles/{externalId}/traits:
    get:
      operationId: getUserTraits
      summary: Get user traits
      description: >-
        Returns the traits for a user profile identified by an external
        ID. The external ID format is type:value, such as
        user_id:abc123 or email:[email protected]. Use the include
        parameter to specify which traits to retrieve for optimal
        performance.
      tags:
        - Traits
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - name: include
          in: query
          description: >-
            Comma-separated list of trait names to include in the
            response. Recommended for best performance.
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: User traits retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traits:
                    type: object
                    description: >-
                      A map of trait names to their values.
                    additionalProperties: true
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/users/profiles/{externalId}/events:
    get:
      operationId: getUserEvents
      summary: Get user events
      description: >-
        Returns the events for a user profile identified by an external
        ID. Events represent the actions the user has taken and are
        returned in reverse chronological order.
      tags:
        - Events
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: User events retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                    description: >-
                      An array of event objects.
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/users/profiles/{externalId}/external_ids:
    get:
      operationId: getUserExternalIds
      summary: Get user external IDs
      description: >-
        Returns the external identifiers linked to a user profile.
        External IDs include user IDs, anonymous IDs, email addresses,
        and other identifiers that have been associated with the profile
        through identity resolution.
      tags:
        - External IDs
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: External IDs retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalId'
                    description: >-
                      An array of external ID objects.
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/users/profiles/{externalId}/metadata:
    get:
      operationId: getUserMetadata
      summary: Get user metadata
      description: >-
        Returns metadata for a user profile, including when the profile
        was created, last updated, and the total count of events and
        traits.
      tags:
        - Profiles
      parameters:
        - $ref: '#/components/parameters/ExternalId'
      responses:
        '200':
          description: User metadata retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment_id:
                    type: string
                    description: >-
                      The internal Segment profile ID.
                  created_at:
                    type: string
                    format: date-time
                    description: >-
                      When the profile was first created.
                  updated_at:
                    type: string
                    format: date-time
                    description: >-
                      When the profile was last updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/users/profiles/{externalId}/links:
    get:
      operationId: getUserLinks
      summary: Get user links
      description: >-
        Returns the linked profiles for a user, such as account-level
        profiles that the user belongs to.
      tags:
        - Links
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: User links retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        to_collection:
                          type: string
                          description: >-
                            The collection the link points to.
                        external_ids:
                          type: array
                          items:
                            $ref: '#/components/schemas/ExternalId'
                          description: >-
                            External IDs of the linked profile.
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/accounts/profiles/{externalId}/traits:
    get:
      operationId: getAccountTraits
      summary: Get account traits
      description: >-
        Returns the traits for an account profile identified by an
        external ID. Account profiles are group-level profiles that
        aggregate data across users.
      tags:
        - Traits
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - name: include
          in: query
          description: >-
            Comma-separated list of trait names to include.
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: Account traits retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  traits:
                    type: object
                    description: >-
                      A map of trait names to their values.
                    additionalProperties: true
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /collections/accounts/profiles/{externalId}/external_ids:
    get:
      operationId: getAccountExternalIds
      summary: Get account external IDs
      description: >-
        Returns the external identifiers linked to an account profile.
      tags:
        - External IDs
      parameters:
        - $ref: '#/components/parameters/ExternalId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Next'
      responses:
        '200':
          description: Account external IDs retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalId'
                    description: >-
                      An array of external ID objects.
                  cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using the Profile API access token
        as the username and an empty password. Access tokens are
        generated in the Segment Unify space settings.
  parameters:
    ExternalId:
      name: externalId
      in: path
      required: true
      description: >-
        The external ID used to look up the profile. Format is
        type:value, such as user_id:abc123, email:[email protected],
        or anonymous_id:xyz789.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: >-
        The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 100
    Next:
      name: next
      in: query
      description: >-
        Pagination cursor to retrieve the next page of results.
      schema:
        type: string
  responses:
    Unauthorized:
      description: >-
        Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      The error code.
                  message:
                    type: string
                    description: >-
                      A human-readable error message.
    NotFound:
      description: >-
        The requested profile was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      The error code.
                  message:
                    type: string
                    description: >-
                      A human-readable error message.
    RateLimited:
      description: >-
        Too many requests. The Profile API enforces rate limits
        per space.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      The error code.
                  message:
                    type: string
                    description: >-
                      A human-readable error message.
  schemas:
    Cursor:
      type: object
      properties:
        url:
          type: string
          description: >-
            The URL to retrieve the next page.
        has_more:
          type: boolean
          description: >-
            Whether there are more results.
        next:
          type: string
          description: >-
            The cursor value for the next page.
        limit:
          type: integer
          description: >-
            The number of items per page.
    Event:
      type: object
      properties:
        type:
          type: string
          description: >-
            The type of event.
          enum:
            - identify
            - track
            - page
            - screen
            - group
            - alias
        event:
          type: string
          description: >-
            The name of the event, for track events.
        properties:
          type: object
          description: >-
            Properties associated with the event.
          additionalProperties: true
        traits:
          type: object
          description: >-
            Traits associated with the event, for identify events.
          additionalProperties: true
        context:
          type: object
          description: >-
            Context information for the event.
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: >-
            When the event occurred.
        messageId:
          type: string
          description: >-
            Unique identifier for the event.
        source_id:
          type: string
          description: >-
            The ID of the source that sent the event.
    ExternalId:
      type: object
      properties:
        id:
          type: string
          description: >-
            The value of the external ID.
        type:
          type: string
          description: >-
            The type of external ID.
          enum:
            - user_id
            - anonymous_id
            - email
            - phone
            - cross_domain_id
            - android.id
            - android.idfa
            - ios.id
            - ios.idfa
        source_id:
          type: string
          description: >-
            The source that provided this external ID.
        collection:
          type: string
          description: >-
            The collection this external ID belongs to.
        created_at:
          type: string
          format: date-time
          description: >-
            When this external ID was first seen.
        encoding:
          type: string
          description: >-
            The encoding of the ID value.