> ## Documentation Index
> Fetch the complete documentation index at: https://flywheel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Track User Event

> Track a user event to build comprehensive user profiles and trigger automated workflows. Events represent user actions, behaviors, and interactions with your product that you want to track and analyze.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/events
openapi: 3.0.0
info:
  title: Flywheel API
  description: >-
    Complete API for tracking events, sending transactional emails, and building
    comprehensive user profiles
  version: 1.0.0
  contact:
    email: support@flywheel.cx
servers:
  - url: https://api.flywheel.cx
    description: Production server
security:
  - apiKeyAuth: []
    authTypeHeader: []
paths:
  /v1/events:
    post:
      tags:
        - Events
      summary: Track User Event
      description: >-
        Track a user event to build comprehensive user profiles and trigger
        automated workflows. Events represent user actions, behaviors, and
        interactions with your product that you want to track and analyze.
      operationId: postEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event
              properties:
                event:
                  $ref: '#/components/schemas/PostEventRequest'
            examples:
              user_signup:
                summary: User signup event
                value:
                  event:
                    event: user_signup
                    user_id: user123
                    properties:
                      source: website
                      plan: premium
                      utm_source: google_ads
                      utm_campaign: summer2024
              product_purchased:
                summary: Product purchase event
                value:
                  event:
                    event: product_purchased
                    user_id: user456
                    timestamp: '2024-01-15T10:30:00Z'
                    properties:
                      product_name: Premium Plan
                      price: 99.99
                      currency: USD
                      payment_method: credit_card
                      order_id: ord_123456
              anonymous_event:
                summary: Anonymous user event
                value:
                  event:
                    event: page_viewed
                    anonymous_id: anon_789
                    properties:
                      page: /pricing
                      referrer: https://google.com
                      device_type: mobile
              identify_user:
                summary: Event with user identification
                value:
                  event:
                    event: user_updated_profile
                    user_id: user456
                    identify: true
                    properties:
                      email: john.doe@company.com
                      first_name: John
                      last_name: Doe
                      phone: +1-555-0123
                      company: Tech Corp
                      plan_type: premium
      responses:
        '200':
          description: Event tracked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
              examples:
                success:
                  summary: Successful event tracking
                  value:
                    success: true
                    message: Event tracked successfully
        '400':
          description: Bad request - Invalid event data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Validation error
                  value:
                    error: 'Validation failed: event name is required'
                    code: VALIDATION_ERROR
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal server error
components:
  schemas:
    PostEventRequest:
      type: object
      required:
        - event
      properties:
        event:
          type: string
          description: >-
            The name/type of the event. Use descriptive, consistent naming
            (e.g., 'user_signup', 'product_purchased', 'page_viewed')
          example: user_signup
          pattern: ^[a-zA-Z0-9_-]+$
        user_id:
          type: string
          description: >-
            Unique identifier for the user who performed the action. If not
            provided, the event will be tracked as anonymous
          example: user123
        timestamp:
          type: string
          format: date-time
          description: >-
            When the event occurred in ISO 8601 format with timezone offset. If
            not provided, the current server time will be used
          example: '2024-01-15T10:30:00Z'
        event_id:
          type: string
          description: >-
            Optional unique identifier for this specific event occurrence. If
            not provided, a UUID will be generated automatically
          example: evt_123456789
        properties:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: boolean
              - type: number
              - type: string
                format: date-time
          description: >-
            Additional data associated with the event. Can include any
            business-specific information relevant to the event
          example:
            source: website
            plan: premium
            price: 99.99
            is_trial: false
            signup_date: '2024-01-15T10:30:00Z'
        anonymous_id:
          type: string
          description: >-
            Anonymous identifier for users who haven't been identified yet.
            Useful for tracking anonymous visitors before they sign up or log in
          example: anon_789012345
        identify:
          type: boolean
          description: >-
            When set to true, triggers user identification and profile
            creation/update before the event is processed. This extracts user
            properties from the event data and creates or updates the user
            profile with identifiable information like email, phone, name, etc.
            If false or omitted, the event is processed without explicit user
            identification.
          example: true
          default: false
    EventResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the event was tracked successfully
          example: true
        message:
          type: string
          description: Success message
          example: Event tracked successfully
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        code:
          type: string
          description: Error code for programmatic handling
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Enter your API key obtained from the Flywheel dashboard (without 'Bearer
        ' prefix)
    authTypeHeader:
      type: apiKey
      in: header
      name: Auth-Type
      description: Authentication type header. Must be set to 'api' for all API requests.
      x-default: api
      x-example: api

````