segment Traits API

openapi: 3.2.0
info:
  title: Segment Profile Traits 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/
servers:
- url: https://profiles.segment.com/v1/spaces/{spaceId}
  description: Production Server
  variables:
    spaceId:
      description: The ID of the Segment Unify space.
      default: ''
security:
- basicAuth: []
tags:
- name: Traits
  description: Operations for retrieving computed and custom traits for user and account profiles.
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:user@example.com. 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/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'
components:
  responses:
    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.
    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.
  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:user@example.com, 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
  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.
  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.
externalDocs:
  description: Segment Profile API Documentation
  url: https://segment.com/docs/unify/profile-api/