segment Events API

openapi: 3.2.0
info:
  title: Segment Profile Events 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: Events
  description: Operations for retrieving events associated with a user or account profile.
paths:
  /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'
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:
    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.
    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/