Profiles

Profiles are profiles imported from external sources and events, unified through identity resolution, and stored in the workspace's data warehouse.

Endpoints

List profiles

Retrieves profiles stored in the workspace's data warehouse, up to a maximum number of profiles defined by limit. You must specify which properties to include. If a filter is provided, only profiles that match the filter criteria will be returned.

Request

properties
array of string
The names of the properties to return. If no properties are specified, all properties are returned.
filter
object
The filter used to select profiles based on their attribute values. Only the profiles 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":"email","operator":"is","values":["my.friend@example.com"]}]}

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%22email%22%2c%22operator%22%3a%22is%22%2c%22values%22%3a%5b%22my.friend%40example.com%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 profiles to be returned. It can be any property from the profile schema with a sortable type, meaning it cannot be of type json, array, object, or map.

If not provided, the profiles are ordered by their update time.
orderDesc
boolean
Indicates if the returned profiles are sorted in descending order; if not true, they are sorted in ascending order.
first
int
The number of profiles to skip before starting to return results. The default value is 0.
limit
int
The maximum number of profiles to return. It can be any value between 1 and 1,000. If not provided, the default value is 100.

Response

profiles
array of object
- kpid
  uuid
  The Krenalis Profile ID.
- updatedAt
  datetime
  The date and time when the profile's attributes were last updated in the sources. It corresponds to the most recent update among its identities.
- attributes
  json
  The attributes of the profile, compliant with the workspace's profile schema. Only the properties requested in the query are included.
schema
schema
The portion of the profile schema that describes the returned attributes. It includes only the properties specified in the request.
total
int
An estimate of the total number of profiles, without considering first and limit.

GET /v1/profiles

curl -G https://example.com/v1/profiles \
  -H "Authorization: Bearer api_xxxxxxx" \
  -d "properties=first_name,last_name,email" \
  -d "order=email" \
  -d "orderDesc=true" \
  -d "limit=100"

Response

{
  "profiles": [
    {
      "kpid": "02bc2281-f801-4f59-9c56-b96ff81df84f",
      "updatedAt": "2025-12-10T09:05:14.137139Z",
      "attributes": {
        "first_name": "John",
        "last_name": "Walker",
        "email": "walker@example.com"
      }
    }
  ],
  "schema": {
    "kind": "object",
    "properties": [
      {
        "name": "first_name",
        "type": {
          "maxLength": 100,
          "kind": "string"
        },
        "readOptional": true,
        "description": "First name"
      },
      {
        "name": "last_name",
        "type": {
          "maxLength": 100,
          "kind": "string"
        },
        "readOptional": true,
        "description": "Last name"
      },
      {
        "name": "email",
        "type": {
          "maxLength": 254,
          "kind": "string"
        },
        "readOptional": true,
        "description": "Email"
      }
    ]
  },
  "total": 803154
}

Errors

404

workspace does not exist

422

data warehouse is in maintenance mode

422

property does not exist in the profile schema

422

order does not exist in schema

422

cannot sort by non-sortable type

Retrieve profile attributes

Retrieves, from the workspace's data warehouse, the attributes of a profile given its KPID (Krenalis Profile ID).

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

Request

:kpid
uuid Required
The Krenalis Profile ID.

Response

attributes
json
The attributes of the profile, compliant with the workspace's profile schema.

GET /v1/profiles/:kpid/attributes

curl https://example.com/v1/profiles/02bc2281-f801-4f59-9c56-b96ff81df84f/attributes \
  -H "Authorization: Bearer api_xxxxxxx"

Response

{
  "attributes": {
    "name": "John Walker",
    "email": "walker@example.com"
  }
}

Errors

404

workspace does not exist

422

data warehouse is in maintenance mode

404

profile does not exist

Retrieve profile events

Retrieves the most recent events for a profile given their KPID (Krenalis Profile ID). The events are read from the workspace's data warehouse and are listed in descending order, starting with the most recent ones.

This endpoint provides a streamlined, profile-focused alternative to the List events endpoint.

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

Request

:kpid
uuid Required
The Krenalis Profile ID.
properties
array of string
The names of the event properties to return. If no properties are specified, all properties are returned.
limit
int
The maximum number of events to return. It can be any value between 1 and 1,000. If not provided, the default value is 100.

Response

events
array of object
The most recent events of the profile. An empty array is returned if no events are available or if the specified profile does not exist.
- kpid
  uuid Optional
  The Krenalis Profile ID that identifies the profile associated with the event.
  
  It is missing if the event has not yet been linked to a profile.
- connectionId
  int
  The identifier of the source connection from which the event was 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/profiles/:kpid/events

curl -G https://example.com/v1/profiles/02bc2281-f801-4f59-9c56-b96ff81df84f/events \
  -H "Authorization: Bearer api_xxxxxxx" \
  -d "properties=kpid,connectionId,anonymousId,context,event,messageId,properties,receivedAt,sentAt,originalTimestamp,timestamp,type,userId"

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

Retrieve profile identities

Retrieves, from the workspace's data warehouse, the identities of a profile given its KPID (Krenalis Profile ID).

Identities are sorted by last update time in descending order, so the most recently updated identities appear first.

If the profile does not exist, no identities are returned.

Request

:kpid
uuid Required
The Krenalis Profile ID.
first
int
The number of identities to skip before starting to return results. The default value is 0.
limit
int
The maximum number of identities to return. It can be any value between 1 and 1,000. If not provided, the default value is 100.

Response

identities
array of object
The profile's identities. It is empty if the profile has no identities.
- userId
  string Optional
  The unique identifier that represents the user in the source from which the identity was read. Specifically:
  - For SDK and webhook connections, it corresponds to the User ID of the event.
  - For an application connection, it is the value used to identify the user in the application. For example, in HubSpot's application, it corresponds to the HubSpot ID.
  - For a database or file storage connection, it is the value in the column designated as the identity.
  Optional: This field is not present for anonymous identities.
- anonymousIds
  array of string Optional
  The anonymous IDs of the identity.
  
  Optional: This field is present only for identities imported from events.
- connection
  int
  The ID of the connection through which the identity was read.
- pipeline
  int
  The ID of the pipeline through which the identity was imported.
- updatedAt
  datetime
  The date and time when the identity's attributes were last updated in the source.
total
int
The total number of identities linked to the profile.

GET /v1/profiles/:kpid/identities

curl https://example.com/v1/profiles/86de98fe-8f26-49ac-87dc-8a14997a97d9/identities \
  -H "Authorization: Bearer api_xxxxxxx"

Response

{
  "identities": [
    {
      "userId": "b8c24mEpaxC",
      "connection": 1604839201,
      "pipeline": 932174586,
      "updatedAt": "2025-12-04 16:17:28.637905Z"
    },
    {
      "anonymousIds": [
        "9f60d802-903b-4d89-81b4-80ae1be56cd7"
      ],
      "connection": 941501877,
      "pipeline": 1775371637,
      "updatedAt": "2025-12-02 13:05:49.381546Z"
    },
    {
      "userId": "u7x49LpQm12",
      "anonymousIds": [
        "0b12df7a-22c4-4a34-a8f0-7e20b219bc11",
        "c41f8d90-55ae-4b19-9b8d-2c5c77ce905c"
      ],
      "connection": 1734820012,
      "pipeline": 1083375521,
      "updatedAt": "2025-12-06 10:22:13.128901Z"
    }
  ],
  "total": 12
}

Errors

404

workspace does not exist

422

data warehouse is in maintenance mode

Profiles

List profiles

Request

properties

filter

filter.logical

filter.conditions

property

operator

values

order

orderDesc

first

limit

Response

profiles

kpid

updatedAt

attributes

schema

total

Retrieve profile attributes

Request

:kpid

Response

attributes

Retrieve profile events

Request

:kpid

properties

limit

Response

events

kpid

connectionId

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.other

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