Events

Events are customer behavioral events (such as page views, clicks, or purchases) received from websites, mobile apps, and servers. They can be stored in the workspace's data warehouse and forwarded to applications. You can also import customer data for identity resolution and unification.

These endpoints allow you to ingest events, List events from the data warehouse, get the event schema, and manage event listeners.

Endpoints

Ingest events

This endpoint allows you to ingest a batch of events.

You can also use one of the available SDKs to send events, instead of interacting with this endpoint directly.

Authentication

It supports authentication with both an API key and an event write key:

For a website or mobile app, you must exclusively use an event write key, as it only provides access to event ingestion endpoints.
For a server application, using an event write key is recommended if you don't need access to other endpoints.

Alternative payloads

Alternatively, when using an event write key, you can also pass the array of events directly in the request body.

If there is a single event to ingest, you can pass the event object directly, similar to the Ingest event endpoint, but specifying the event type in the request body.

Browser requests and CORS

This endpoint supports cross-origin requests from browsers (CORS) and handle preflight OPTIONS requests, unlike other API endpoints, which are intended for server-to-server use.

If you send events from a website or web application, we recommend using the JavaScript SDK, which automatically manages CORS and authentication details.

If you experience CORS-related errors in the browser, make sure that:

requests are sent to this event ingestion endpoint;
you are using an event write key;
the request is not routed through a proxy or CDN that blocks OPTIONS requests.

Request

connectionId
int Conditionally Required
The ID of the source connection to which the events refer. It can only be a source SDK or webhook connection.

It is required only if the call is authenticated using an API key. If authentication is done with an event write key, it is not needed, as the connection is that of the key.
batch
array of object Required
The events to ingest.
- anonymousId
  nullable string Conditionally Required
  A unique identifier assigned to a user before authentication, used to track anonymous activity across sessions.
  
  Either anonymousId or userId must be provided, and neither can be null or empty.
- channel
  string
  The source channel through which the event was received (e.g., web, mobile, server).
- category
  nullable string Conditionally Required
  It is used to group related pages or screens for analysis and reporting. It is allowed only for page events.
- context
  object
  Information about the environment where the event occurred.
  - context.app
    object
    The application that sent the event.
    - context.app.name
      string
      The application name.
    - context.app.version
      string
      The application version.
    - context.app.build
      string
      The application build identifier.
    - context.app.namespace
      string
      The application namespace or internal identifier.
  - context.browser
    object
    The browser from which the event originates.
    
    If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
    - context.browser.name
      string
      The name of the browser from which the event originated.
      
      Krenalis tries to normalize this field and store it with one of those names: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet" or "Opera".
      
      Otherwise, if the passed browser name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.browser.other.
    - context.browser.version
      string
      The version of the browser from which the event originated.
  - context.campaign
    object
    The campaign that originated the event.
    - context.campaign.name
      string
      The campaign name.
    - context.campaign.source
      string
      The campaign source.
    - context.campaign.medium
      string
      The campaign medium (e.g. email, social).
    - context.campaign.term
      string
      The campaign keyword or term.
    - context.campaign.content
      string
      The campaign content or variation.
  - context.device
    object
    The device from which the event originated.
    - context.device.id
      string
      The device identifier.
    - context.device.advertisingId
      string
      The advertising identifier.
    - context.device.adTrackingEnabled
      boolean
      Indicates whether ad tracking is enabled.
    - context.device.manufacturer
      string
      The device manufacturer.
    - context.device.model
      string
      The device model.
    - context.device.name
      string
      The device name.
    - context.device.type
      string
      The device type (e.g., mobile, desktop).
    - context.device.token
      string
      The unique device token.
  - context.ip
    ip
    The IP address associated with the event. If not specified, for JavaScript, Android and iOS connections, the event's IP address is automatically derived from the HTTP request.
    
    The following special values let you change the default behavior and control how the IP address is determined or masked:
    - "255.255.255.255": Use the IP address of the request.
    - "255.255.255.0": Use the IP address of the request, masking it with 255.255.255.0, which sets the last segment to 0 (e.g., 192.168.45.32 → 192.168.45.0). Use this for partial anonymization.
    - "255.255.0.0": Use the IP address of the request, masking it with 255.255.0.0, which sets the last two segments to 0 (e.g., 192.168.45.32 → 192.168.0.0). Use this for stronger anonymization.
    - "0.0.0.0": Don't include an IP address in the event. Use this with JavaScript, Android and iOS connections when no IP address is applicable or when it should not be associated for privacy reasons.
  - context.library
    object
    The analytics library used to send the event.
    - context.library.name
      string
      The name of the analytics library.
    - context.library.version
      string
      The version of the analytics library.
  - context.locale
    string
    The user's language and regional settings, such as "en-US".
  - context.location
    object
    The device location from which the event originated. If not explicitly provided, Krenalis attempts to determine it automatically based on the event's IP.
    - context.location.city
      string
      The city.
    - context.location.country
      string
      The country.
    - context.location.latitude
      float
      The latitude.
    - context.location.longitude
      float
      The longitude.
    - context.location.speed
      float
      The speed at which the device is moving, in meters per second.
  - context.network
    object
    The network to which the device originating the event is connected.
    - context.network.bluetooth
      boolean
      Indicates whether Bluetooth is active.
    - context.network.carrier
      string
      The mobile network carrier name.
    - context.network.cellular
      boolean
      Indicates whether a cellular connection is active.
    - context.network.wifi
      boolean
      Indicates whether Wi-Fi is active.
  - context.os
    object
    The OS of the device or browser from which the event originated.
    
    If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
    - context.os.name
      string
      The name of the OS.
      
      Krenalis tries to normalize this field and store it with one of those names: "Android", "Windows", "macOS", "iOS", "Linux" or "Chrome OS".Otherwise, if the passed OS name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.os.other.
    - context.os.version
      string
      The version of the OS.
  - context.page
    object
    The page where the event originated.
    - context.page.path
      string
      The page path.
    - context.page.referrer
      string
      The referring URL.
    - context.page.search
      string
      The URL search parameters.
    - context.page.title
      string
      The page title.
    - context.page.url
      string
      The full page URL.
  - context.referrer
    object
    The URL of the page or source that referred the user to the current page.
    - context.referrer.id
      string
      The identifier of the referring source (e.g., campaign or partner ID).
    - context.referrer.type
      string
      The source category of the referrer (e.g., search, social, email).
  - context.screen
    object
    The screen of the app where the event was originated.
    - context.screen.width
      16 bit int
      The screen width. Must be in range [1, 32767].
    - context.screen.height
      16 bit int
      The screen height. Must be in range [1, 32767].
    - context.screen.density
      decimal(3, 2)
      The screen density. Must be a positive number.
  - context.session
    object
    The current user session
    - context.session.id
      64 bit int
      The session identifier.
    - context.session.start
      boolean
      Indicates whether the event starts a session.
  - context.sessionId
    64 bit int
    The session identifier. This field can be passed as an alternative to context.session.id for compatibility with RudderStack.
  - context.sessionStart
    boolean
    Indicates whether the event started a session. This field can be passed as an alternative to context.session.start for compatibility with RudderStack.
  - context.timezone
    string
    The user's timezone as a tzdata string (e.g., America/New_York).
  - context.userAgent
    string
    The device identifier from which the event originates.
- event
  string Conditionally Required
  The name of the user action in a track event. Examples: Product Viewed, Order Completed.
  
  It is required only for track events. For all other types of events, it is not permitted.
- groupId
  nullable string Conditionally Required
  Identifier of the group (e.g., account, company, organization) associated with the user.
  
  It is required only for group events. For all other types of events, it is not permitted.
- messageId
  nullable string
  The ID that uniquely identifies the event. If it is missing or null, a generated identifier will be used as its value.
- name
  string
  The title of the viewed page or screen in page and screen events.
  
  It is allowed only for page and screen events.
- properties
  json
  A key–value pairs describing contextual details about the event (e.g., product_id, revenue, rating). Distinct from traits, which describe user attributes.
  
  It is allowed only for page, screen, and track events.
- sentAt
  datetime
  An UTC timestamp indicating when the event was sent, in ISO 8601 format. The year must be in the range 1 to 9999.
- originalTimestamp
  nullable datetime
  An UTC timestamp indicating when the event occurred on the client, in ISO 8601 format. The year must be in the range 1 to 9999.
  
  Pass this property if the event occurred in the past.
- timestamp
  nullable datetime Conditionally Required
  An UTC timestamp indicating when the event occurred, in ISO 8601 format. The year must be in the range 1 to 9999.
  
  It will be adjusted by Krenalis to account for clock drift.
  
  It is required if the property originalTimestamp is present.
- traits
  json Conditionally Required
  A key–value pairs containing user information (e.g., name, email, plan).
  
  It is allowed only for identify and group events. You can use context.traits for other types of events.
- type
  string Required
  The event type.
  Possible values: "alias", "identify", "group", "page", "screen" or "track".
- previousId
  string Conditionally Required
  The user's previous identifier. Not used by Krenalis.
  
  It is required only for alias events. For all other types of events, it is not permitted.
- userId
  nullable string Conditionally Required
  The unique identifier assigned to a user after authentication. If absent, the user is anonymous.
  
  It is required and cannot be null or empty for identify and alias events. For other event types, either anonymousId or userId must be provided, and neither can be null or empty.
context
object
This object defines shared context data applied to every event in the batch. If a property appears in both the global context and an event's own context, the event-specific value takes precedence.
- context.app
  object
  The application that sent the event.
  - context.app.name
    string
    The application name.
  - context.app.version
    string
    The application version.
  - context.app.build
    string
    The application build identifier.
  - context.app.namespace
    string
    The application namespace or internal identifier.
- context.browser
  object
  The browser from which the event originates.
  
  If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
  - context.browser.name
    string
    The name of the browser from which the event originated.
    
    Krenalis tries to normalize this field and store it with one of those names: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet" or "Opera".
    
    Otherwise, if the passed browser name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.browser.other.
  - context.browser.version
    string
    The version of the browser from which the event originated.
- context.campaign
  object
  The campaign that originated the event.
  - context.campaign.name
    string
    The campaign name.
  - context.campaign.source
    string
    The campaign source.
  - context.campaign.medium
    string
    The campaign medium (e.g. email, social).
  - context.campaign.term
    string
    The campaign keyword or term.
  - context.campaign.content
    string
    The campaign content or variation.
- context.device
  object
  The device from which the event originated.
  - context.device.id
    string
    The device identifier.
  - context.device.advertisingId
    string
    The advertising identifier.
  - context.device.adTrackingEnabled
    boolean
    Indicates whether ad tracking is enabled.
  - context.device.manufacturer
    string
    The device manufacturer.
  - context.device.model
    string
    The device model.
  - context.device.name
    string
    The device name.
  - context.device.type
    string
    The device type (e.g., mobile, desktop).
  - context.device.token
    string
    The unique device token.
- context.ip
  ip
  The IP address associated with the event. If not specified, for JavaScript, Android and iOS connections, the event's IP address is automatically derived from the HTTP request.
  
  The following special values let you change the default behavior and control how the IP address is determined or masked:
  - "255.255.255.255": Use the IP address of the request.
  - "255.255.255.0": Use the IP address of the request, masking it with 255.255.255.0, which sets the last segment to 0 (e.g., 192.168.45.32 → 192.168.45.0). Use this for partial anonymization.
  - "255.255.0.0": Use the IP address of the request, masking it with 255.255.0.0, which sets the last two segments to 0 (e.g., 192.168.45.32 → 192.168.0.0). Use this for stronger anonymization.
  - "0.0.0.0": Don't include an IP address in the event. Use this with JavaScript, Android and iOS connections when no IP address is applicable or when it should not be associated for privacy reasons.
- context.library
  object
  The analytics library used to send the event.
  - context.library.name
    string
    The name of the analytics library.
  - context.library.version
    string
    The version of the analytics library.
- context.locale
  string
  The user's language and regional settings, such as "en-US".
- context.location
  object
  The device location from which the event originated. If not explicitly provided, Krenalis attempts to determine it automatically based on the event's IP.
  - context.location.city
    string
    The city.
  - context.location.country
    string
    The country.
  - context.location.latitude
    float
    The latitude.
  - context.location.longitude
    float
    The longitude.
  - context.location.speed
    float
    The speed at which the device is moving, in meters per second.
- context.network
  object
  The network to which the device originating the event is connected.
  - context.network.bluetooth
    boolean
    Indicates whether Bluetooth is active.
  - context.network.carrier
    string
    The mobile network carrier name.
  - context.network.cellular
    boolean
    Indicates whether a cellular connection is active.
  - context.network.wifi
    boolean
    Indicates whether Wi-Fi is active.
- context.os
  object
  The OS of the device or browser from which the event originated.
  
  If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
  - context.os.name
    string
    The name of the OS.
    
    Krenalis tries to normalize this field and store it with one of those names: "Android", "Windows", "macOS", "iOS", "Linux" or "Chrome OS".Otherwise, if the passed OS name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.os.other.
  - context.os.version
    string
    The version of the OS.
- context.page
  object
  The page where the event originated.
  - context.page.path
    string
    The page path.
  - context.page.referrer
    string
    The referring URL.
  - context.page.search
    string
    The URL search parameters.
  - context.page.title
    string
    The page title.
  - context.page.url
    string
    The full page URL.
- context.referrer
  object
  The URL of the page or source that referred the user to the current page.
  - context.referrer.id
    string
    The identifier of the referring source (e.g., campaign or partner ID).
  - context.referrer.type
    string
    The source category of the referrer (e.g., search, social, email).
- context.screen
  object
  The screen of the app where the event was originated.
  - context.screen.width
    16 bit int
    The screen width. Must be in range [1, 32767].
  - context.screen.height
    16 bit int
    The screen height. Must be in range [1, 32767].
  - context.screen.density
    decimal(3, 2)
    The screen density. Must be a positive number.
- context.session
  object
  The current user session
  - context.session.id
    64 bit int
    The session identifier.
  - context.session.start
    boolean
    Indicates whether the event starts a session.
- context.sessionId
  64 bit int
  The session identifier. This field can be passed as an alternative to context.session.id for compatibility with RudderStack.
- context.sessionStart
  boolean
  Indicates whether the event started a session. This field can be passed as an alternative to context.session.start for compatibility with RudderStack.
- context.timezone
  string
  The user's timezone as a tzdata string (e.g., America/New_York).
- context.userAgent
  string
  The device identifier from which the event originates.
sentAt
datetime
An UTC timestamp indicating when the event was sent, in ISO 8601 format. The year must be in the range 1 to 9999. The sentAt value of each event, if present, overwrites this value.
writeKey
string
The event write key of the connection, which can be used for authentication as an alternative to the Authorization header.

Response

No response.

POST /v1/events

curl https://example.com/v1/events \
  -H "Authorization: Bearer api_xxxxxxx" \
  --json '{
    "connectionId": 1371036433,
    "batch": [
      {
        "anonymousId": "3e93e10e-5ca0-4a8c-bef6-cf9197b37729",
        "context": {
          "page": {
            "path": "/dashboard",
            "title": "User Dashboard",
            "url": "https://app.example.com/dashboard"
          },
          "screen": {
            "width": 3024,
            "height": 1964,
            "density": 2
          },
          "session": {
            "id": 1766272512048,
            "start": true
          },
          "timezone": "America/Los_Angeles",
          "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15"
        },
        "event": "Workout Completed",
        "messageId": "82c8516b-434b-48f4-a32c-a6369e1543fd",
        "properties": {
          "workout_type": "Cardio",
          "duration_minutes": 45,
          "calories_burned": 380,
          "device": "Smartwatch"
        },
        "sentAt": "2025-10-20T16:15:24.327Z",
        "timestamp": "2025-10-20T16:15:24.010Z",
        "type": "track",
        "userId": "802661375"
      }
    ]
  }'

Errors

404

workspace does not exist

422

data warehouse is in maintenance mode

Ingest event

Ingests a single event.

This endpoint supports authentication only with an event write key. To ingest events with an API key, use the Ingest events endpoint, which supports both authentication methods.

You can also use one of the available SDKs to send events, instead of interacting with this endpoint directly.

Browser requests and CORS

This endpoint supports cross-origin requests from browsers (CORS) and handle preflight OPTIONS requests, unlike other API endpoints, which are intended for server-to-server use.

If you send events from a website or web application, we recommend using the JavaScript SDK, which automatically manages CORS and authentication details.

If you experience CORS-related errors in the browser, make sure that:

requests are sent to this event ingestion endpoint;
you are using an event write key;
the request is not routed through a proxy or CDN that blocks OPTIONS requests.

Request

:type
string Required
The type of the event.
Possible values: "alias", "identify", "group", "page", "screen" or "track".
anonymousId
nullable string Conditionally Required
A unique identifier assigned to a user before authentication, used to track anonymous activity across sessions.

Either anonymousId or userId must be provided, and neither can be null or empty.
channel
string
The source channel through which the event was received (e.g., web, mobile, server).
category
nullable string Conditionally Required
It is used to group related pages or screens for analysis and reporting. It is allowed only for page events.
context
object
Information about the environment where the event occurred.
- context.app
  object
  The application that sent the event.
  - context.app.name
    string
    The application name.
  - context.app.version
    string
    The application version.
  - context.app.build
    string
    The application build identifier.
  - context.app.namespace
    string
    The application namespace or internal identifier.
- context.browser
  object
  The browser from which the event originates.
  
  If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
  - context.browser.name
    string
    The name of the browser from which the event originated.
    
    Krenalis tries to normalize this field and store it with one of those names: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet" or "Opera".
    
    Otherwise, if the passed browser name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.browser.other.
  - context.browser.version
    string
    The version of the browser from which the event originated.
- context.campaign
  object
  The campaign that originated the event.
  - context.campaign.name
    string
    The campaign name.
  - context.campaign.source
    string
    The campaign source.
  - context.campaign.medium
    string
    The campaign medium (e.g. email, social).
  - context.campaign.term
    string
    The campaign keyword or term.
  - context.campaign.content
    string
    The campaign content or variation.
- context.device
  object
  The device from which the event originated.
  - context.device.id
    string
    The device identifier.
  - context.device.advertisingId
    string
    The advertising identifier.
  - context.device.adTrackingEnabled
    boolean
    Indicates whether ad tracking is enabled.
  - context.device.manufacturer
    string
    The device manufacturer.
  - context.device.model
    string
    The device model.
  - context.device.name
    string
    The device name.
  - context.device.type
    string
    The device type (e.g., mobile, desktop).
  - context.device.token
    string
    The unique device token.
- context.ip
  ip
  The IP address associated with the event. If not specified, for JavaScript, Android and iOS connections, the event's IP address is automatically derived from the HTTP request.
  
  The following special values let you change the default behavior and control how the IP address is determined or masked:
  - "255.255.255.255": Use the IP address of the request.
  - "255.255.255.0": Use the IP address of the request, masking it with 255.255.255.0, which sets the last segment to 0 (e.g., 192.168.45.32 → 192.168.45.0). Use this for partial anonymization.
  - "255.255.0.0": Use the IP address of the request, masking it with 255.255.0.0, which sets the last two segments to 0 (e.g., 192.168.45.32 → 192.168.0.0). Use this for stronger anonymization.
  - "0.0.0.0": Don't include an IP address in the event. Use this with JavaScript, Android and iOS connections when no IP address is applicable or when it should not be associated for privacy reasons.
- context.library
  object
  The analytics library used to send the event.
  - context.library.name
    string
    The name of the analytics library.
  - context.library.version
    string
    The version of the analytics library.
- context.locale
  string
  The user's language and regional settings, such as "en-US".
- context.location
  object
  The device location from which the event originated. If not explicitly provided, Krenalis attempts to determine it automatically based on the event's IP.
  - context.location.city
    string
    The city.
  - context.location.country
    string
    The country.
  - context.location.latitude
    float
    The latitude.
  - context.location.longitude
    float
    The longitude.
  - context.location.speed
    float
    The speed at which the device is moving, in meters per second.
- context.network
  object
  The network to which the device originating the event is connected.
  - context.network.bluetooth
    boolean
    Indicates whether Bluetooth is active.
  - context.network.carrier
    string
    The mobile network carrier name.
  - context.network.cellular
    boolean
    Indicates whether a cellular connection is active.
  - context.network.wifi
    boolean
    Indicates whether Wi-Fi is active.
- context.os
  object
  The OS of the device or browser from which the event originated.
  
  If not explicitly provided, Krenalis will attempt to infer it from the context.userAgent property, if available.
  - context.os.name
    string
    The name of the OS.
    
    Krenalis tries to normalize this field and store it with one of those names: "Android", "Windows", "macOS", "iOS", "Linux" or "Chrome OS".Otherwise, if the passed OS name cannot be normalized, it is set to "Other" and the passed name is stored — as is — into context.os.other.
  - context.os.version
    string
    The version of the OS.
- context.page
  object
  The page where the event originated.
  - context.page.path
    string
    The page path.
  - context.page.referrer
    string
    The referring URL.
  - context.page.search
    string
    The URL search parameters.
  - context.page.title
    string
    The page title.
  - context.page.url
    string
    The full page URL.
- context.referrer
  object
  The URL of the page or source that referred the user to the current page.
  - context.referrer.id
    string
    The identifier of the referring source (e.g., campaign or partner ID).
  - context.referrer.type
    string
    The source category of the referrer (e.g., search, social, email).
- context.screen
  object
  The screen of the app where the event was originated.
  - context.screen.width
    16 bit int
    The screen width. Must be in range [1, 32767].
  - context.screen.height
    16 bit int
    The screen height. Must be in range [1, 32767].
  - context.screen.density
    decimal(3, 2)
    The screen density. Must be a positive number.
- context.session
  object
  The current user session
  - context.session.id
    64 bit int
    The session identifier.
  - context.session.start
    boolean
    Indicates whether the event starts a session.
- context.sessionId
  64 bit int
  The session identifier. This field can be passed as an alternative to context.session.id for compatibility with RudderStack.
- context.sessionStart
  boolean
  Indicates whether the event started a session. This field can be passed as an alternative to context.session.start for compatibility with RudderStack.
- context.timezone
  string
  The user's timezone as a tzdata string (e.g., America/New_York).
- context.userAgent
  string
  The device identifier from which the event originates.
event
string Conditionally Required
The name of the user action in a track event. Examples: Product Viewed, Order Completed.

It is required only for track events. For all other types of events, it is not permitted.
groupId
nullable string Conditionally Required
Identifier of the group (e.g., account, company, organization) associated with the user.

It is required only for group events. For all other types of events, it is not permitted.
messageId
nullable string
The ID that uniquely identifies the event. If it is missing or null, a generated identifier will be used as its value.
name
string
The title of the viewed page or screen in page and screen events.

It is allowed only for page and screen events.
properties
json
A key–value pairs describing contextual details about the event (e.g., product_id, revenue, rating). Distinct from traits, which describe user attributes.

It is allowed only for page, screen, and track events.
sentAt
datetime
An UTC timestamp indicating when the event was sent. The year must be in the range 1 to 9999.
originalTimestamp
nullable datetime
An UTC timestamp indicating when the event occurred on the client, in ISO 8601 format. The year must be in the range 1 to 9999.

Pass this property if the event occurred in the past.
timestamp
nullable datetime Conditionally Required
An UTC timestamp indicating when the event occurred, in ISO 8601 format. The year must be in the range 1 to 9999.

It will be adjusted by Krenalis to account for clock drift.

It is required if the property originalTimestamp is present.
traits
json
A key–value pairs containing user information (e.g., name, email, plan).

It is allowed only for identify and group events. You can use context.traits for other types of events.
previousId
string Conditionally Required
The user's previous identifier. Not used by Krenalis.

It is required only for alias events. For all other types of events, it is not permitted.
userId
nullable string Conditionally Required
The unique identifier assigned to a user after authentication. If absent, the user is anonymous.

It is required and cannot be null or empty for identify and alias events. For other event types, either anonymousId or userId must be provided, and neither can be null or empty.

Response

No response.

POST /v1/events/:type

curl https://example.com/v1/events/track \
  -H "Authorization: Bearer xxxxxxx" \
  --json '{
    "anonymousId": "3e93e10e-5ca0-4a8c-bef6-cf9197b37729",
    "context": {
      "page": {
        "path": "/dashboard",
        "title": "User Dashboard",
        "url": "https://app.example.com/dashboard"
      },
      "screen": {
        "width": 3024,
        "height": 1964,
        "density": 2
      },
      "session": {
        "id": 1766272512048,
        "start": true
      },
      "timezone": "America/Los_Angeles",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15"
    },
    "event": "Workout Completed",
    "messageId": "82c8516b-434b-48f4-a32c-a6369e1543fd",
    "properties": {
      "workout_type": "Cardio",
      "duration_minutes": 45,
      "calories_burned": 380,
      "device": "Smartwatch"
    },
    "sentAt": "2025-10-20T16:15:24.327Z",
    "timestamp": "2025-10-20T16:15:24.010Z",
    "userId": "802661375"
  }'

List events

Retrieves events stored in the workspace's data warehouse, ordered by default from most recently received to oldest, up to the maximum number of events specified by limit. If a filter is provided, only events that match the filter criteria will be returned.

You can also query events directly from the events view in your workspace's data warehouse.

Request

properties
array of string
The names of the event properties to return. If no properties are specified, all properties are returned.
filter
object
The filter applied to the events. Only the events that match the filter will be returned.

It must be encoded in JSON, then escaped for the context of the query string. So, for example, the JSON-encoded filter:

{"logical":"and","conditions":[{"property":"kpid","operator":"is","values":["960ae86c-fc6e-438a-ae03-838fa6c94946"]}]}

must be escaped and passed in the query string, for example as follows:

filter=%7b%22logical%22%3a%22and%22%2c%22conditions%22%3a%5b%7b%22property%22%3a%22kpid%22%2c%22operator%22%3a%22is%22%2c%22values%22%3a%5b%22960ae86c-fc6e-438a-ae03-838fa6c94946%22%5d%7d%5d%7d
- filter.logical
  string Required Possible values: "and" or "or".
- filter.conditions
  array of object Required
  A filter's condition.
  - property
    string Required
    The name or path of the property. If the property has a json type, it can include a json path.
  - operator
    string Required
    The condition's operator. The allowed values depend on the property's type.
    Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".
  - values
    array of string
    The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.
order
string
The name of the property by which to sort the events to be returned.

If not provided, the events are sorted by timestamp.
Possible values: "kpid", "connectionId", "anonymousId", "channel", "category", "event", "groupId", "messageId", "name", "receivedAt", "sentAt", "originalTimestamp", "timestamp", "type" or "userId".
ascending
boolean
Indicates whether the returned events are sorted in ascending order. If not provided or set to false, the events are sorted in descending order.
first
int
The number of events to skip before starting to return results. If not provided, no events are skipped.
limit
int
The maximum number of events to return. The value must be within the range [1, 1000]. If not provided, the default value is 100.

Response

events
array of object
- kpid
  uuid Optional
  The ID of the Krenalis user associated with the event, if any; otherwise, this field is absent.
  
  kpid is set for each event by the Identity Resolution process, and its value may change over time depending on how users are unified and associated with events.
- connectionId
  int
  The ID of the source connection from which the event originates. Automatically set by Krenalis when the event is received.
- anonymousId
  string
  A unique identifier assigned to a user before authentication, used to track anonymous activity across sessions.
- channel
  string Optional
  The source channel through which the event was received (e.g., web, mobile, server).
- category
  string Optional
  It is used to group related pages or screens for analysis and reporting.
- context
  object Optional
  Information about the environment where the event occurred. If there's no information in the context, this field is not returned.
  - context.app
    object Optional
    The application that sent the event.
    - context.app.name
      string Optional
      The application name.
    - context.app.version
      string Optional
      The application version.
    - context.app.build
      string Optional
      The application build identifier.
    - context.app.namespace
      string Optional
      The application namespace or internal identifier.
  - context.browser
    object Optional
    The browser from which the event originated.
    - context.browser.name
      string Optional
      The name of the browser from which the event originated.
      
      If the value is "Other", then the field other is populated with the browser name.
      Possible values: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet", "Opera" or "Other".
    - context.browser.other
      string Optional
      The name of the browser in case it is not one of those recognized by Krenalis.
      
      This field is present only when name is "Other".
    - context.browser.version
      string Optional
      The version of the browser from which the event originated.
  - context.campaign
    object Optional
    The campaign that originated the event.
    - context.campaign.name
      string Optional
      The campaign name.
    - context.campaign.source
      string Optional
      The campaign source.
    - context.campaign.medium
      string Optional
      The campaign medium (e.g. "email", "social").
    - context.campaign.term
      string Optional
      The campaign keyword or term.
    - context.campaign.content
      string Optional
      The campaign content or variation.
  - context.device
    object Optional
    The device from which the event originated.
    
    For iOS, note that model identifiers may differ from marketed names (e.g., "iPhone16,2" for iPhone 15 Pro Max).
    - context.device.id
      string Optional
      The device identifier.
    - context.device.advertisingId
      string Optional
      The advertising identifier.
    - context.device.adTrackingEnabled
      boolean Optional
      Indicates whether ad tracking is enabled.
    - context.device.manufacturer
      string Optional
      The device manufacturer.
    - context.device.model
      string Optional
      The device model.
    - context.device.name
      string Optional
      The device name.
    - context.device.type
      string Optional
      The device type (e.g., mobile, desktop).
    - context.device.token
      string Optional
      The unique device token.
  - context.ip
    ip Optional
    The IP address associated with the event.
  - context.library
    object Optional
    The analytics library used to send the event.
    - context.library.name
      string Optional
      The name of the analytics library.
    - context.library.version
      string Optional
      The version of the analytics library.
  - context.locale
    string Optional
  - context.location
    object Optional
    Device location from which the event was originated.
    - context.location.city
      string Optional
      The city.
    - context.location.country
      string Optional
      The country.
    - context.location.latitude
      float Optional
      The latitude.
    - context.location.longitude
      float Optional
      The longitude.
    - context.location.speed
      float Optional
      The speed at which the device is moving, in meters per second.
  - context.network
    object Optional
    The network to which the device originating the event was connected.
    - context.network.bluetooth
      boolean Optional
      Indicates whether Bluetooth is active.
    - context.network.carrier
      string Optional
      The mobile network carrier name.
    - context.network.cellular
      boolean Optional
      Indicates whether a cellular connection is active.
    - context.network.wifi
      boolean Optional
      Indicates whether Wi-Fi is active.
  - context.os
    object Optional
    The OS of the device or browser from which the event was originated.
    - context.os.name
      string Optional
      The name of the OS from which the event was originated.
      
      If the value is "Other", then the field other is populated with the OS name.
      Possible values: "Android", "Windows", "iOS", "macOS", "Linux", "Chrome OS" or "Other".
    - context.os.other
      string Optional
      The name of the OS in case it is not one of those recognized by Krenalis.
      
      This field is present only when name is "Other".
    - context.os.version
      string Optional
      The version of the OS.
  - context.page
    object Optional
    The page where the event originated.
    - context.page.path
      string Optional
      The page path.
    - context.page.referrer
      string Optional
      The referring URL.
    - context.page.search
      string Optional
      The URL search parameters.
    - context.page.title
      string Optional
      The page title.
    - context.page.url
      string Optional
      The full page URL.
  - context.referrer
    object Optional
    The URL of the page or source that referred the user to the page where the event originated.
    - context.referrer.id
      string Optional
      The identifier of the referring source (e.g., campaign or partner ID).
    - context.referrer.type
      string Optional
      The source category of the referrer (e.g., search, social, email).
  - context.screen
    object Optional
    The screen of the app where the event was originated.
    - context.screen.width
      16 bit int Optional
      The screen width.
    - context.screen.height
      16 bit int Optional
      The screen height.
    - context.screen.density
      decimal(3, 2) Optional
      The screen density. It is a positive number.
  - context.session
    object Optional
    The user session when the event was generated.
    - context.session.id
      64 bit int Optional
      The session identifier.
    - context.session.start
      boolean Optional
      Indicates whether the event started a session.
  - context.timezone
    string Optional
    The user's timezone as a tzdata string (e.g., "America/New_York").
  - context.userAgent
    string Optional
    The device identifier from which the event originated.
- event
  string Optional
  Identifies a track-type event, for example with a value like Product Purchased. For any other event type, it is never returned.
- groupId
  string Optional
  The group ID related to the event. Returned only for group-type event, and absent for all other event types.
- messageId
  string
  The ID that uniquely identifies the event.
- name
  string Optional
  The title of the viewed page or screen in page and screen events. Not returned for other event types.
- properties
  json Optional
  A key–value pairs describing contextual details about the event (e.g., product_id, revenue, rating). Distinct from traits, which describe user attributes.
- receivedAt
  datetime
  An UTC timestamp indicating when the event was received. Set by Krenalis.
- sentAt
  datetime
  An UTC timestamp indicating when the event was sent by the client. Not reliable for analysis due to potential client clock drift; use timestamp for analytics.
- originalTimestamp
  datetime
  An UTC timestamp indicating when the event occurred on the client, in ISO 8601 format. Not recommended for analysis due to possible clock drift; use timestamp instead.
- timestamp
  datetime
  An UTC timestamp indicating when the event occurred, in ISO 8601 format. Suitable for analysis.
- traits
  json
  A key–value pairs containing user information (e.g., name, email, plan).
  
  This field is always returned, regardless of the event type.
  
  If there are no traits, an empty JSON object is returned.
- type
  string
  The event type: one of "page", "screen", "track", "identify", "group", or "alias".
  Possible values: "alias", "identify", "group", "page", "screen" or "track".
- previousId
  string Optional
  The user's previous identifier.
- userId
  string Optional
  The unique identifier assigned to a user after authentication. If absent, the user is anonymous.

GET /v1/events

curl -G https://example.com/v1/events \
  -H "Authorization: Bearer api_xxxxxxx" \
  -d "properties=kpid,connectionId,anonymousId,context,event,messageId,properties,receivedAt,sentAt,originalTimestamp,timestamp,type,userId" \
  -d "limit=50"

Response

{
  "events": [
    {
      "kpid": "9102d2a1-0714-4c13-bafd-8a38bc3d0cff",
      "connectionId": 1371036433,
      "anonymousId": "3e93e10e-5ca0-4a8c-bef6-cf9197b37729",
      "context": {
        "browser": {
          "name": "Safari",
          "version": "17.2.1"
        },
        "ip": "172.91.24.57",
        "library": {
          "name": "krenalis.js",
          "version": "1.0.0"
        },
        "locale": "en-US",
        "os": {
          "name": "macOS",
          "version": "14.5"
        },
        "page": {
          "path": "/dashboard",
          "title": "User Dashboard",
          "url": "https://app.example.com/dashboard"
        },
        "screen": {
          "width": 3024,
          "height": 1964,
          "density": 2
        },
        "session": {
          "id": "1766272512048"
        },
        "timezone": "America/Los_Angeles",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15"
      },
      "event": "Workout Completed",
      "messageId": "82c8516b-434b-48f4-a32c-a6369e1543fd",
      "properties": {
        "workout_type": "Cardio",
        "duration_minutes": 45,
        "calories_burned": 380,
        "device": "Smartwatch"
      },
      "receivedAt": "2025-10-20T16:15:24.340Z",
      "sentAt": "2025-10-20T16:15:24.327Z",
      "originalTimestamp": "2025-10-20T16:15:23.992Z",
      "timestamp": "2025-10-20T16:15:24.010Z",
      "type": "track",
      "userId": "720572415"
    }
  ]
}

Errors

404

workspace does not exist

422

data warehouse is in maintenance mode

Get event schema

Return the event schema. The event schema is the same for all workspaces.

Request

No parameters.

Response

schema
schema

GET /v1/events/schema

curl https://example.com/v1/events/schema \
  -H "Authorization: Bearer api_xxxxxxx"

Response

{
  "schema": {
    "kind": "object",
    "properties": [
      {
        "name": "kpid",
        "type": {
          "kind": "uuid"
        },
        "readOptional": true,
        "description": "Krenalis Profile ID"
      },
      {
        "name": "connectionId",
        "type": {
          "kind": "int",
          "bitSize": 32
        },
        "description": "Connection ID"
      },
      {
        "name": "anonymousId",
        "type": {
          "kind": "string"
        },
        "description": "Anonymous ID"
      },
      {
        "name": "channel",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Channel"
      },
      {
        "name": "category",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Category"
      },
      {
        "name": "context",
        "type": {
          "kind": "object",
          "properties": [
            {
              "name": "app",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "name",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "version",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Version"
                  },
                  {
                    "name": "build",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Build"
                  },
                  {
                    "name": "namespace",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Namespace"
                  }
                ]
              },
              "readOptional": true,
              "description": "App"
            },
            {
              "name": "browser",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "name",
                    "type": {
                      "kind": "string",
                      "values": [
                        "Chrome",
                        "Safari",
                        "Edge",
                        "Firefox",
                        "Samsung Internet",
                        "Opera",
                        "Other"
                      ]
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "other",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Other"
                  },
                  {
                    "name": "version",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Version"
                  }
                ]
              },
              "readOptional": true,
              "description": "Browser"
            },
            {
              "name": "campaign",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "name",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "source",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Source"
                  },
                  {
                    "name": "medium",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Medium"
                  },
                  {
                    "name": "term",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Term"
                  },
                  {
                    "name": "content",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Content"
                  }
                ]
              },
              "readOptional": true,
              "description": "Campaign"
            },
            {
              "name": "device",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "id",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Id"
                  },
                  {
                    "name": "advertisingId",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Advertising ID"
                  },
                  {
                    "name": "adTrackingEnabled",
                    "type": {
                      "kind": "boolean"
                    },
                    "readOptional": true,
                    "description": "Ad tracking enabled"
                  },
                  {
                    "name": "manufacturer",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Manufacturer"
                  },
                  {
                    "name": "model",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Model"
                  },
                  {
                    "name": "name",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "type",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Type"
                  },
                  {
                    "name": "token",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Token"
                  }
                ]
              },
              "readOptional": true,
              "description": "Device"
            },
            {
              "name": "ip",
              "type": {
                "kind": "ip"
              },
              "readOptional": true,
              "description": "IP"
            },
            {
              "name": "library",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "name",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "version",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Version"
                  }
                ]
              },
              "readOptional": true,
              "description": "Library"
            },
            {
              "name": "locale",
              "type": {
                "kind": "string"
              },
              "readOptional": true,
              "description": "Locale"
            },
            {
              "name": "location",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "city",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "City"
                  },
                  {
                    "name": "country",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Country"
                  },
                  {
                    "name": "latitude",
                    "type": {
                      "kind": "float",
                      "bitSize": 64
                    },
                    "readOptional": true,
                    "description": "Latitude"
                  },
                  {
                    "name": "longitude",
                    "type": {
                      "kind": "float",
                      "bitSize": 64
                    },
                    "readOptional": true,
                    "description": "Longitude"
                  },
                  {
                    "name": "speed",
                    "type": {
                      "kind": "float",
                      "bitSize": 64
                    },
                    "readOptional": true,
                    "description": "Speed"
                  }
                ]
              },
              "readOptional": true,
              "description": "Location"
            },
            {
              "name": "network",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "bluetooth",
                    "type": {
                      "kind": "boolean"
                    },
                    "readOptional": true,
                    "description": "Bluetooth"
                  },
                  {
                    "name": "carrier",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Carrier"
                  },
                  {
                    "name": "cellular",
                    "type": {
                      "kind": "boolean"
                    },
                    "readOptional": true,
                    "description": "Cellular"
                  },
                  {
                    "name": "wifi",
                    "type": {
                      "kind": "boolean"
                    },
                    "readOptional": true,
                    "description": "Wi-Fi"
                  }
                ]
              },
              "readOptional": true,
              "description": "Network"
            },
            {
              "name": "os",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "name",
                    "type": {
                      "kind": "string",
                      "values": [
                        "Android",
                        "Windows",
                        "iOS",
                        "macOS",
                        "Linux",
                        "Chrome OS",
                        "Other"
                      ]
                    },
                    "readOptional": true,
                    "description": "Name"
                  },
                  {
                    "name": "other",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Other"
                  },
                  {
                    "name": "version",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Version"
                  }
                ]
              },
              "readOptional": true,
              "description": "OS"
            },
            {
              "name": "page",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "path",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Path"
                  },
                  {
                    "name": "referrer",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Referrer"
                  },
                  {
                    "name": "search",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Search"
                  },
                  {
                    "name": "title",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Title"
                  },
                  {
                    "name": "url",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "URL"
                  }
                ]
              },
              "readOptional": true,
              "description": "Page"
            },
            {
              "name": "referrer",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "id",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "ID"
                  },
                  {
                    "name": "type",
                    "type": {
                      "kind": "string"
                    },
                    "readOptional": true,
                    "description": "Type"
                  }
                ]
              },
              "readOptional": true,
              "description": "Referrer"
            },
            {
              "name": "screen",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "width",
                    "type": {
                      "kind": "int",
                      "bitSize": 16
                    },
                    "readOptional": true,
                    "description": "Width"
                  },
                  {
                    "name": "height",
                    "type": {
                      "kind": "int",
                      "bitSize": 16
                    },
                    "readOptional": true,
                    "description": "Height"
                  },
                  {
                    "name": "density",
                    "type": {
                      "kind": "decimal",
                      "precision": 3,
                      "scale": 2
                    },
                    "readOptional": true,
                    "description": "Density"
                  }
                ]
              },
              "readOptional": true,
              "description": "Screen"
            },
            {
              "name": "session",
              "type": {
                "kind": "object",
                "properties": [
                  {
                    "name": "id",
                    "type": {
                      "kind": "int",
                      "bitSize": 64
                    },
                    "readOptional": true,
                    "description": "ID"
                  },
                  {
                    "name": "start",
                    "type": {
                      "kind": "boolean"
                    },
                    "readOptional": true,
                    "description": "Start"
                  }
                ]
              },
              "readOptional": true,
              "description": "Session"
            },
            {
              "name": "timezone",
              "type": {
                "kind": "string"
              },
              "readOptional": true,
              "description": "Timezone"
            },
            {
              "name": "userAgent",
              "type": {
                "kind": "string"
              },
              "readOptional": true,
              "description": "User agent"
            }
          ]
        },
        "readOptional": true,
        "description": "Context"
      },
      {
        "name": "event",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Event"
      },
      {
        "name": "groupId",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Group ID"
      },
      {
        "name": "messageId",
        "type": {
          "kind": "string"
        },
        "description": "Message ID"
      },
      {
        "name": "name",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Name"
      },
      {
        "name": "properties",
        "type": {
          "kind": "json"
        },
        "readOptional": true,
        "description": "Properties"
      },
      {
        "name": "receivedAt",
        "type": {
          "kind": "datetime"
        },
        "description": "Received at"
      },
      {
        "name": "sentAt",
        "type": {
          "kind": "datetime"
        },
        "description": "Sent at"
      },
      {
        "name": "originalTimestamp",
        "type": {
          "kind": "datetime"
        },
        "description": "Original timestamp"
      },
      {
        "name": "timestamp",
        "type": {
          "kind": "datetime"
        },
        "description": "Timestamp"
      },
      {
        "name": "traits",
        "type": {
          "kind": "json"
        },
        "description": "Traits"
      },
      {
        "name": "type",
        "type": {
          "kind": "string",
          "values": [
            "alias",
            "identify",
            "group",
            "page",
            "screen",
            "track"
          ]
        },
        "description": "Type"
      },
      {
        "name": "previousId",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "Previous ID"
      },
      {
        "name": "userId",
        "type": {
          "kind": "string"
        },
        "readOptional": true,
        "description": "User ID"
      }
    ]
  }
}

Errors

404

workspace does not exist

Create event listener

Creates an event listener for the workspace that listens to events and returns its identifier.

Request

connectionId
nullable int
The ID of the source connection that received the events, or of the destination connection where the events are sent. The connection must support events.
size
nullable int
The maximum number of observed events to return. It must be between 1 and 1000. If not specified or set to null, the default is 10.
filter
nullable object
The filter applied to the events. If not null, only events that match the filter will be included.
- filter.logical
  string Required Possible values: "and" or "or".
- filter.conditions
  array of object Required
  A filter's condition.
  - property
    string Required
    The name or path of the property. If the property has a json type, it can include a json path.
  - operator
    string Required
    The condition's operator. The allowed values depend on the property's type.
    Possible values: "is", "is not", "is less than", "is less than or equal to", "is greater than", "is greater than or equal to", "is between", "is not between", "contains", "does not contain", "is one of", "is not one of", "starts with", "ends with", "is before", "is on or before", "is after", "is on or after", "is true", "is false", "is empty", "is not empty", "is null", "is not null", "exists" or "does not exist".
  - values
    array of string
    The values the operator applies to, if any. These depend on both the operator and the property's type, including whether they're present and how many there are.

Response

id
int
The ID of the event listener.

POST /v1/events/listeners

curl https://example.com/v1/events/listeners \
  -H "Authorization: Bearer api_xxxxxxx" \
  --json '{
    "connectionId": 1371036433,
    "size": 10,
    "filter": {
      "logical": "and",
      "conditions": [
        {
          "property": "name",
          "operator": "is",
          "values": [
            "Mary"
          ]
        }
      ]
    }
  }'

Response

{
  "id": "a9081719-e505-405b-95d9-33c77facd987"
}

Errors

404

workspace does not exist

422

connection does not exist

422

there are already 100 listeners

List observed events

Returns the events captured by the specified listener along with the count of omitted events.

Request

:id
int Required
The ID of the event listener.

Response

events
array of object
The observed events.
- connectionId
  int
  The ID of the source connection from which the event originates. Automatically set by Krenalis when the event is received.
- anonymousId
  string
  A unique identifier assigned to a user before authentication, used to track anonymous activity across sessions.
- channel
  string Optional
  The source channel through which the event was received (e.g., web, mobile, server).
- category
  string Optional
  It is used to group related pages or screens for analysis and reporting.
- context
  object Optional
  Information about the environment where the event occurred. If there's no information in the context, this field is not returned.
  - context.app
    object Optional
    The application that sent the event.
    - context.app.name
      string Optional
      The application name.
    - context.app.version
      string Optional
      The application version.
    - context.app.build
      string Optional
      The application build identifier.
    - context.app.namespace
      string Optional
      The application namespace or internal identifier.
  - context.browser
    object Optional
    The browser from which the event originated.
    - context.browser.name
      string Optional
      The name of the browser from which the event originated.
      
      If the value is "Other", then the field other is populated with the browser name.
      Possible values: "Chrome", "Safari", "Edge", "Firefox", "Samsung Internet", "Opera" or "Other".
    - context.browser.other
      string Optional
      The name of the browser in case it is not one of those recognized by Krenalis.
      
      This field is present only when name is "Other".
    - context.browser.version
      string Optional
      The version of the browser from which the event originated.
  - context.campaign
    object Optional
    The campaign that originated the event.
    - context.campaign.name
      string Optional
      The campaign name.
    - context.campaign.source
      string Optional
      The campaign source.
    - context.campaign.medium
      string Optional
      The campaign medium (e.g. "email", "social").
    - context.campaign.term
      string Optional
      The campaign keyword or term.
    - context.campaign.content
      string Optional
      The campaign content or variation.
  - context.device
    object Optional
    The device from which the event originated.
    
    For iOS, note that model identifiers may differ from marketed names (e.g., "iPhone16,2" for iPhone 15 Pro Max).
    - context.device.id
      string Optional
      The device identifier.
    - context.device.advertisingId
      string Optional
      The advertising identifier.
    - context.device.adTrackingEnabled
      boolean Optional
      Indicates whether ad tracking is enabled.
    - context.device.manufacturer
      string Optional
      The device manufacturer.
    - context.device.model
      string Optional
      The device model.
    - context.device.name
      string Optional
      The device name.
    - context.device.type
      string Optional
      The device type (e.g., mobile, desktop).
    - context.device.token
      string Optional
      The unique device token.
  - context.ip
    ip Optional
    The IP address associated with the event.
  - context.library
    object Optional
    The analytics library used to send the event.
    - context.library.name
      string Optional
      The name of the analytics library.
    - context.library.version
      string Optional
      The version of the analytics library.
  - context.locale
    string Optional
  - context.location
    object Optional
    Device location from which the event was originated.
    - context.location.city
      string Optional
      The city.
    - context.location.country
      string Optional
      The country.
    - context.location.latitude
      float Optional
      The latitude.
    - context.location.longitude
      float Optional
      The longitude.
    - context.location.speed
      float Optional
      The speed at which the device is moving, in meters per second.
  - context.network
    object Optional
    The network to which the device originating the event was connected.
    - context.network.bluetooth
      boolean Optional
      Indicates whether Bluetooth is active.
    - context.network.carrier
      string Optional
      The mobile network carrier name.
    - context.network.cellular
      boolean Optional
      Indicates whether a cellular connection is active.
    - context.network.wifi
      boolean Optional
      Indicates whether Wi-Fi is active.
  - context.os
    object Optional
    The OS of the device or browser from which the event was originated.
    - context.os.name
      string Optional
      The name of the OS from which the event was originated.
      
      If the value is "Other", then the field other is populated with the OS name.
      Possible values: "Android", "Windows", "iOS", "macOS", "Linux", "Chrome OS" or "Other".
    - context.os.other
      string Optional
      The name of the OS in case it is not one of those recognized by Krenalis.
      
      This field is present only when name is "Other".
    - context.os.version
      string Optional
      The version of the OS.
  - context.page
    object Optional
    The page where the event originated.
    - context.page.path
      string Optional
      The page path.
    - context.page.referrer
      string Optional
      The referring URL.
    - context.page.search
      string Optional
      The URL search parameters.
    - context.page.title
      string Optional
      The page title.
    - context.page.url
      string Optional
      The full page URL.
  - context.referrer
    object Optional
    The URL of the page or source that referred the user to the page where the event originated.
    - context.referrer.id
      string Optional
      The identifier of the referring source (e.g., campaign or partner ID).
    - context.referrer.type
      string Optional
      The source category of the referrer (e.g., search, social, email).
  - context.screen
    object Optional
    The screen of the app where the event was originated.
    - context.screen.width
      16 bit int Optional
      The screen width.
    - context.screen.height
      16 bit int Optional
      The screen height.
    - context.screen.density
      decimal(3, 2) Optional
      The screen density. It is a positive number.
  - context.session
    object Optional
    The user session when the event was generated.
    - context.session.id
      64 bit int Optional
      The session identifier.
    - context.session.start
      boolean Optional
      Indicates whether the event started a session.
  - context.timezone
    string Optional
    The user's timezone as a tzdata string (e.g., "America/New_York").
  - context.userAgent
    string Optional
    The device identifier from which the event originated.
- event
  string Optional
  Identifies a track-type event, for example with a value like Product Purchased. For any other event type, it is never returned.
- groupId
  string Optional
  The group ID related to the event. Returned only for group-type event, and absent for all other event types.
- messageId
  string
  The ID that uniquely identifies the event.
- name
  string Optional
  The title of the viewed page or screen in page and screen events. Not returned for other event types.
- properties
  json Optional
  A key–value pairs describing contextual details about the event (e.g., product_id, revenue, rating). Distinct from traits, which describe user attributes.
- receivedAt
  datetime
  An UTC timestamp indicating when the event was received. Set by Krenalis.
- sentAt
  datetime
  An UTC timestamp indicating when the event was sent by the client. Not reliable for analysis due to potential client clock drift; use timestamp for analytics.
- originalTimestamp
  datetime
  An UTC timestamp indicating when the event occurred on the client, in ISO 8601 format. Not recommended for analysis due to possible clock drift; use timestamp instead.
- timestamp
  datetime
  An UTC timestamp indicating when the event occurred, in ISO 8601 format. Suitable for analysis.
- traits
  json
  A key–value pairs containing user information (e.g., name, email, plan).
  
  This field is always returned, regardless of the event type.
  
  If there are no traits, an empty JSON object is returned.
- type
  string
  The event type: one of "page", "screen", "track", "identify", "group", or "alias".
  Possible values: "alias", "identify", "group", "page", "screen" or "track".
- previousId
  string Optional
  The user's previous identifier.
- userId
  string Optional
  The unique identifier assigned to a user after authentication. If absent, the user is anonymous.
omitted
int
The number of omitted events.

GET /v1/events/listeners/:id

curl https://example.com/v1/events/listeners/a9081719-e505-405b-95d9-33c77facd987 \
  -H "Authorization: Bearer api_xxxxxxx"

Response

{
  "events": [
    {
      "connectionId": 1371036433,
      "anonymousId": "3e93e10e-5ca0-4a8c-bef6-cf9197b37729",
      "context": {
        "browser": {
          "name": "Safari",
          "version": "17.2.1"
        },
        "ip": "172.91.24.57",
        "library": {
          "name": "krenalis.js",
          "version": "1.0.0"
        },
        "locale": "en-US",
        "os": {
          "name": "macOS",
          "version": "14.5"
        },
        "page": {
          "path": "/dashboard",
          "title": "User Dashboard",
          "url": "https://app.example.com/dashboard"
        },
        "screen": {
          "width": 3024,
          "height": 1964,
          "density": 2
        },
        "session": {
          "id": "1766272512048"
        },
        "timezone": "America/Los_Angeles",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15"
      },
      "event": "Workout Completed",
      "messageId": "82c8516b-434b-48f4-a32c-a6369e1543fd",
      "properties": {
        "workout_type": "Cardio",
        "duration_minutes": 45,
        "calories_burned": 380,
        "device": "Smartwatch"
      },
      "receivedAt": "2025-10-20T16:15:24.340Z",
      "sentAt": "2025-10-20T16:15:24.327Z",
      "originalTimestamp": "2025-10-20T16:15:23.992Z",
      "timestamp": "2025-10-20T16:15:24.010Z",
      "type": "track",
      "userId": "720572415"
    }
  ],
  "omitted": 572
}

Errors

404

workspace does not exist

404

event listener does not exist

Delete event listener

Deletes an event listener. It does nothing if the event listener does not exist.

Request

:id
int Required
The ID of the event listener.

Response

No response.

DELETE /v1/events/listeners/:id

curl -X DELETE https://example.com/v1/events/listeners/a9081719-e505-405b-95d9-33c77facd987 \
  -H "Authorization: Bearer api_xxxxxxx"

Errors

404

workspace does not exist

Events

Ingest events

Authentication

Alternative payloads

Browser requests and CORS

Request

connectionId

batch

anonymousId

channel

category

context

context.app

context.app.name

context.app.version

context.app.build

context.app.namespace

context.browser

context.browser.name

context.browser.version

context.campaign

context.campaign.name

context.campaign.source

context.campaign.medium

context.campaign.term

context.campaign.content

context.device

context.device.id

context.device.advertisingId

context.device.adTrackingEnabled

context.device.manufacturer

context.device.model

context.device.name

context.device.type

context.device.token

context.ip

context.library

context.library.name

context.library.version

context.locale

context.location

context.location.city

context.location.country

context.location.latitude

context.location.longitude

context.location.speed

context.network

context.network.bluetooth

context.network.carrier

context.network.cellular

context.network.wifi

context.os

context.os.name

context.os.version

context.page

context.page.path

context.page.referrer

context.page.search

context.page.title

context.page.url

context.referrer

context.referrer.id

context.referrer.type

context.screen

context.screen.width

context.screen.height

context.screen.density

context.session

context.session.id

context.session.start

context.sessionId

context.sessionStart

context.timezone

context.userAgent

event

groupId

messageId

name

properties

sentAt