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

# Track an event

> This endpoint creates a new event for a user, persisting the event in Permutive for downstream consumption, such as for segmentation, insights, or routing to a data lake. It validates the event against the schema defined in your workspace, and generates an event ID for the event and optionally enriches the event with geo, ISP, and contextual data.

## Event schema

It's important to note that Permutive enforces event schemas to ensure data consistency and validity.

If an event is tracked that does not match the expected schema for the event type, it will be rejected and a `400` error will be returned. Where Permutive hasn't received an event type before, it will infer the event's schema.

Event schemas are viewable in the [Permutive Dashboard](https://dash.permutive.com). To migrate an event schema, please [email support](mailto:support@permutive.com).

## Event size limit

The size of an event's `properties` JSON object is limited to 950 KB to ensure platform performance.

If an event exceeds this size limit, it will be rejected and a 400 error will be returned.

## Time attributes

When streaming in data in real-time (e.g. from within an app), Permutive sets a time attribute for events to the current time in UTC.


## OpenAPI

````yaml POST /events
openapi: 3.1.0
info:
  title: Events API
  version: v2
servers:
  - url: https://api.permutive.app/v2.0
security: []
paths:
  /events:
    post:
      tags:
        - v2.0
      summary: Track an event
      description: >-
        This endpoint creates a new event for a user, persisting the event in
        Permutive for downstream consumption, such as for segmentation,
        insights, or routing to a data lake. It validates the event against the
        schema defined in your workspace, and generates an event ID for the
        event and optionally enriches the event with geo, ISP, and contextual
        data.
      operationId: createEvent
      parameters:
        - name: enrich
          in: query
          description: >-
            This boolean parameter determines whether to enrich the event with
            geo, ISP, and natural language processing data. By default, this is
            set to `true`.
          required: false
          schema:
            type: boolean
        - name: sdkp
          in: query
          description: >-
            This boolean parameter is used to describe whether the event
            originated from a Permutive SDK on a client's device, where `true`
            denotes the event was from an SDK and `false` denotes an out-of-SDK
            event.

             By default, this parameter is set to `true`. If you are interacting with this endpoint directly, rather than through a Permutive SDK, please set this parameter to `false`.
          required: false
          schema:
            type: boolean
      requestBody:
        description: >-
          You must provide **either** a `user_id` **or** a non-empty list
          `aliases` of prioritized aliases to specify the user that the event
          belongs to.

           If a `user_id` is provided, it will be used directly to identify the user, ignoring any aliases provided. If only aliases are provided and none match, a new user ID is generated and the aliases are synced to it.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostEvent'
            examples:
              User ID request:
                summary: User ID request
                description: A request to create an event for a user with a user ID.
                value:
                  name: Pageview
                  user_id: 2008c38f-dece-4570-976d-87593ed001c3
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_string: hello, world!
                    my_number: 42
                    my_boolean: true
                    my_object:
                      inner_property_string: nested value
                      inner_property_integer: 69
              Aliases request:
                summary: Aliases request
                description: A request to create an event for a user with aliases.
                value:
                  name: Pageview
                  aliases:
                    - priority: 0
                      tag: email_sha256
                      id: user@example.com
                    - priority: 1
                      tag: some-third-party-id-provider
                      id: '1234567890'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_string: hello, world!
                    my_number: 42
                    my_boolean: true
                    my_object:
                      inner_property_string: nested value
                      inner_property_integer: 69
        required: true
      responses:
        '201':
          description: Event created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/EventResponse'
                  - $ref: '#/components/schemas/EventUnenrichedResponse'
              examples:
                Enriched:
                  summary: Full response when enrich=true
                  value:
                    name: Pageview
                    user_id: 2008c38f-dece-4570-976d-87593ed001c3
                    time: '2026-01-01T12:00:00.000Z'
                    view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                    session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                    properties:
                      my_string: hello, world!
                      my_number: 42
                      my_boolean: true
                      my_object:
                        inner_property_string: nested value
                        inner_property_integer: 69
                Non-enriched:
                  summary: Minimal response when enrich=false
                  value:
                    user_id: 2008c38f-dece-4570-976d-87593ed001c3
                    time: '2026-01-01T12:00:00.000Z'
        '400':
          description: 'Bad request: malformed body or missing required parameters'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid parameters:
                  summary: Invalid parameters
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: BadRequest
                      code: 1000
                      message: The values of one or more parameters are invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing request body:
                  summary: Missing request body
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: BadRequest
                      code: 1003
                      message: A request body was expected but not found.
                      docs: https://docs.permutive.com/api/errors
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: >-
                        The resource requires authentication, which was not
                        supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: >-
                    An error of unspecified nature was encountered while
                    processing your request. Feel free to get in touch with us
                    at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
        - Header: []
        - Parameter: []
components:
  schemas:
    PostEvent:
      title: PostEvent
      type: object
      required:
        - name
      properties:
        user_id:
          type: string
          format: uuid
          description: |-
            The Permutive user ID of the user that the event belongs to.

             If you do not provide a user ID, you must provide a non-empty list of aliases in the `aliases` field.
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritizedAlias'
          minItems: 1
          description: >-
            A non-empty list of prioritized aliases that the user is associated
            with. If you do not provide a list of aliases, you must provide a
            user ID in the `user_id` field.

             Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities.

             When multiple aliases are provided, priorities are used to determine the order in which aliases are attempted for resolution to a Permutive user ID, where priority `0` has the highest priority.
        name:
          type: string
          description: >-
            The name of the event collection this event belongs to. The name is
            case-insensitive and must only contain characters in `[a-zA-Z0-9_]`.
        view_id:
          type: string
          format: uuid
          description: >-
            The identifier for the view in which the event is taking place. This
            is used to group events within a single page or screen view.
        session_id:
          type: string
          format: uuid
          description: >-
            The identifier for the session in which the event is taking place.
            This is used to group events within a user session.
        segments:
          type: array
          items:
            type: integer
          description: >-
            The list of segment codes that the user belonged to at the time of
            the event.
        cohorts:
          type: array
          items:
            type: string
          description: >-
            The list of cohort IDs that the user belonged to at the time of the
            event.
        properties:
          type: object
          title: JSON
          description: >-
            The properties that belong to this event. These properties must
            adhere to the specific schema configured for this event collection.
    EventResponse:
      title: Event response (regular)
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID of the user that the tracked event belongs to.
        name:
          type: string
          description: >-
            The name of the event collection the tracked event belongs to. The
            name is case-insensitive and must only contain characters in
            `[a-zA-Z0-9_]`.
        time:
          type: string
          format: date-time
          description: The ISO 8601 timestamp of the event.
        view_id:
          type: string
          format: uuid
          description: The identifier for the view in which the tracked event took place.
        session_id:
          type: string
          format: uuid
          description: >-
            The identifier for the session in which the tracked event took
            place.
        segments:
          type: array
          items:
            type: integer
          description: >-
            The list of segment codes that the user belonged to at the time the
            event was tracked.
        cohorts:
          type: array
          items:
            type: string
          description: >-
            The list of cohort IDs that the user belonged to at the time the
            event was tracked.
        properties:
          type: object
          title: JSON
          description: >-
            The properties that belong to the tracked event. These properties
            adhere to the specific schema configured for this event collection.
    EventUnenrichedResponse:
      title: Event response (unenriched)
      type: object
      required:
        - user_id
        - time
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID of the user that the tracked event belongs to.
        time:
          type: string
          format: date-time
          description: The ISO 8601 timestamp of the event.
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
        - request_id
        - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          description: Details of the error that occurred.
          required:
            - status
            - code
            - message
            - docs
          properties:
            status:
              type: string
              enum:
                - BadRequest
                - Unauthorized
                - NotFound
                - Conflict
                - Gone
                - InternalServerError
                - Forbidden
              description: The type of error that occurred.
            code:
              type: integer
              format: int32
              description: A numeric code that identifies the error.
            message:
              type: string
              description: A human-readable message describing the error.
            docs:
              type: string
              format: uri
              description: A URL to the documentation for the error.
            cause:
              type: string
              description: >-
                A human-readable message describing additional details of the
                error.
    PrioritizedAlias:
      title: PrioritizedAlias
      type: object
      required:
        - priority
        - tag
        - id
      properties:
        priority:
          type: integer
          format: int32
          description: The priority of the alias, where `0` is the highest priority.
        tag:
          type: string
          description: >-
            The tag is a string used to identify the type of alias, e.g.
            `email_sha256` or `myInternalID`.
        id:
          type: string
          description: >-
            The identifier for the alias, e.g. `user@example.com` or
            `1234567890`.
    RequestId:
      title: RequestId
      type: string
      format: uuid
      description: A unique identifier for the request that caused the error.
  securitySchemes:
    Header:
      type: apiKey
      name: X-API-Key
      in: header
    Parameter:
      type: apiKey
      name: k
      in: query

````