RudderStack Events Schema

Detailed technical documentation of the RudderStack Events Schema API calls and properties of the returned objects.

As a part of RudderStack's Enterprise plan, the RudderStack Events Schema API gives you full access to all your events' metadata. This includes information such as the schema of the event payload, data types, versions of event payload, etc.

This documentation describes all of the available calls in the Event Schema API, as well as the properties of the returned objects as a result.

Getting Started - Obtaining the Credentials

You can start your RudderStack data plane with the environment variables RUDDER_ADMIN_USER and RUDDER_ADMIN_PASSWORD . If you are using the RudderStack-managed hosting service, please contact us for the necessary credentials.

Anyone with these credentials can use the same event schemas API. In case it is compromised, please restart your data plane with different credentials.

API Authentication

You will need to use HTTP Basic Authentication for authenticating the APIs.

You can send the API calls using CURL/HTTPie from the command line, or with any programming language of your choice.

Understanding API responses

All successful requests will respond with a 200 HTTP status code. If the authentication fails, you will get a 400 HTTP status code with the appropriate error message.

API Reference

Please note that the base URL for all the API requests will be your data plane URL.

schemas/event-models

Description

Arguments

Supported Method Types

Gets the event models for your data plane

None required. You may optionally add writeKey as a query parameter to get event-models for only one source

GET

Example Request

To get all event models for your data plane, run the following command:

curl -u <RUDDER_ADMIN_USER>:<RUDDER_ADMIN_PASSWORD> https://<your-data-plane-url>/schemas/event-models

Example Response

[
{
"CreatedAt": "2020-07-24T06:21:11.662211Z",
"ID": 1,
"EventID": "96f10d53-3a94-47a2-95e7-6cca99daed1e",
"EventIdentifier": "android-logged-in",
"EventType": "track",
"WriteKey": "1cUFbgdRJj8LYpA6zGV3O5dGpAq"
},
{
"CreatedAt": "2020-07-24T06:21:16.663609Z",
"ID": 2,
"EventID": "7a2b63c3-df2b-46e4-b999-721da236d091",
"EventIdentifier": "ios-logged-in",
"EventType": "track",
"WriteKey": "1dnv1Xnjawd840MemG6wmwOshf9"
}
]

Getting All Event Models for a Specific Source

To get all event models for a specific source, pass the write key as a query parameter, as shown:

curl -u <RUDDER_ADMIN_USER>:<RUDDER_ADMIN_PASSWORD> https://<your_data_plane_url>/schemas/event-models\\?writeKey=1cUFbgdRJj8LYpA6zGV3O5dGpAq

Example Response

[
{
"CreatedAt": "2020-07-24T06:21:11.662211Z",
"ID": 1,
"EventID": "96f10d53-3a94-47a2-95e7-6cca99daed1e",
"EventIdentifier": "android-logged-in",
"EventType": "track",
"WriteKey": "1cUFbgdRJj8LYpA6zGV3O5dGpAq"
}

schemas/event-versions

Description

Arguments

Supported Method Types

Gets the schema versions for an event type.

eventID is a mandatory query parameter to get the schema versions for an event model. This is obtained from the above API

(event-models).

GET

Example Request

To get schema versions for your event type, run the following command:

curl -u <RUDDER_ADMIN_USER>:<RUDDER_ADMIN_PASSWORD> https://<your-data-plane-url>/schemas/event-versions?eventID=96f10d53-3a94-47a2-95e7-6cca99daed1e

Example Response

[
{
"EventID": "96f10d53-3a94-47a2-95e7-6cca99daed1e",
"FirstSeen": "2020-07-24T06:21:11.662211Z",
"ID": 1,
"LastSeen": "2020-07-24T06:21:21.668532Z",
"Schema": {
"anonymousId": "string",
"channel": "string",
"context.app.build": "string",
"context.app.name": "string",
"context.app.namespace": "string",
"context.app.version": "string",
"context.device.id": "string",
"context.device.manufacturer": "string",
"context.device.model": "string",
"context.device.name": "string",
"context.library.name": "string",
"context.locale": "string",
"context.network.carrier": "string",
"context.screen.density": "float64",
"context.screen.height": "float64",
"context.screen.width": "float64",
"context.traits.anonymousId": "string",
"context.user_agent": "string",
"event": "string",
"integrations.All": "bool",
"messageId": "string",
"originalTimestamp": "string",
"properties.category": "string",
"properties.ec": "string",
"properties.ev": "string",
"properties.label": "string",
"sentAt": "string",
"type": "string"
},
"VersionID": "ad00285b-f49f-4d4f-88e0-8ec293bbd5c7",
"TotalCount": 42
}
]

schemas/event-metadata

Description

Arguments

Supported Method Types

Gets the metadata for a schema-version

versionID is a mandatory query parameter to get metadata for a schema-version. This is obtained from the above API.

GET

The metadata of given schema-version comes with three information points:

  • SampledEvents: This includes the sample events that follow the given schema-version

  • TotalCount: Represents the number of events collected with the given schema-version

  • FrequentValues: This is a list of all values that frequently appear for each key in the schema along with their frequencies. By default, we consider any value that is seen once every hundred samples as a frequent value

Example Request

To get metadata for your schema-versions, run the following command:

curl -u <RUDDER_ADMIN_USER>:<RUDDER_ADMIN_PASSWORD> https://<your-data-plane-url>/schemas/event-metadata?versionID=ad00285b-f49f-4d4f-88e0-8ec293bbd5c7

Example Response

{
"SampledEvents": [
{
"anonymousId": "anon_id",
"channel": "android-sdk",
"context": {
"app": {
"build": "1",
"name": "RudderAndroidClient",
"namespace": "com.rudderlabs.android.sdk",
"version": "1.0"
},
"device": {
"id": "49e4bdd1c280bc00",
"manufacturer": "Google",
"model": "Android SDK built for x86",
"name": "generic_x86"
},
"library": {
"name": "com.rudderstack.android.sdk.core"
},
"locale": "en-US",
"network": {
"carrier": "Android"
},
"screen": {
"density": 420,
"height": 1794,
"width": 1080
},
"traits": {
"anonymousId": "49e4bdd1c280bc00"
},
"user_agent": "Dalvik/2.1.0 (Linux; U; Android 9; Android SDK built for x86 Build/PSR1.180720.075)"
},
"event": "Demo Track",
"integrations": {
"All": true
},
"messageId": "78773889-e485-4316-89e1-69123cfa49df",
"originalTimestamp": "2019-08-12T05:08:30.909Z",
"properties": {
"category": "Demo Category",
"label": "Demo Label",
"value": 5
},
"sentAt": "2019-08-12T05:08:30.909Z",
"type": "track"
},
{
"anonymousId": "anon_id_2",
"channel": "android-sdk",
"context": {
"app": {
"build": "1",
"name": "RudderAndroidClient",
"namespace": "com.rudderlabs.android.sdk",
"version": "1.0"
},
"device": {
"id": "49e4bdd1c280bc00",
"manufacturer": "Google",
"model": "Android SDK built for x86",
"name": "generic_x86"
},
"library": {
"name": "com.rudderstack.android.sdk.core"
},
"locale": "en-US",
"network": {
"carrier": "Android"
},
"screen": {
"density": 420,
"height": 1794,
"width": 1080
},
"traits": {
"anonymousId": "49e4bdd1c280bc00"
},
"user_agent": "Dalvik/2.1.0 (Linux; U; Android 9; Android SDK built for x86 Build/PSR1.180720.075)"
},
"event": "Demo Track",
"integrations": {
"All": true
},
"messageId": "db144617-f9e5-4c52-b893-2661c8f7ab43",
"originalTimestamp": "2019-08-12T05:08:30.909Z",
"properties": {
"category": "Demo Category",
"label": "Demo Label",
"value": 5
},
"sentAt": "2019-08-12T05:08:30.909Z",
"type": "track"
}
],
"TotalCount": 2,
"FrequentValues": {
"anonymousId": [
{
"Value": "anon_id_2",
"Frequency": 0.51
},
{
"Value": "anon_id",
"Frequency": 0.51
}
],
"channel": [
{
"Value": "android-sdk",
"Frequency": 1
}
],
"context.app.build": [
{
"Value": "1",
"Frequency": 1
}
],
"context.app.name": [
{
"Value": "RudderAndroidClient",
"Frequency": 1
}
],
"context.app.namespace": [
{
"Value": "com.rudderlabs.android.sdk",
"Frequency": 1
}
],
"context.app.version": [
{
"Value": "1.0",
"Frequency": 1
}
],
"context.device.id": [
{
"Value": "49e4bdd1c280bc00",
"Frequency": 1
}
],
"context.device.manufacturer": [
{
"Value": "Google",
"Frequency": 1
}
],
"context.device.model": [
{
"Value": "Android SDK built for x86",
"Frequency": 1
}
],
"context.device.name": [
{
"Value": "generic_x86",
"Frequency": 1
}
],
"context.library.name": [
{
"Value": "com.rudderstack.android.sdk.core",
"Frequency": 1
}
],
"context.locale": [
{
"Value": "en-US",
"Frequency": 1
}
],
"context.network.carrier": [
{
"Value": "Android",
"Frequency": 1
}
],
"context.screen.density": [
{
"Value": "420",
"Frequency": 1
}
],
"context.screen.height": [
{
"Value": "1794",
"Frequency": 1
}
],
"context.screen.width": [
{
"Value": "1080",
"Frequency": 1
}
],
"context.traits.anonymousId": [
{
"Value": "49e4bdd1c280bc00",
"Frequency": 1
}
],
"context.user_agent": [
{
"Value": "Dalvik/2.1.0 (Linux; U; Android 9; Android SDK built for x86 Build/PSR1.180720.075)",
"Frequency": 1
}
],
"event": [
{
"Value": "Demo Track",
"Frequency": 1
}
],
"integrations.All": [
{
"Value": "true",
"Frequency": 1
}
],
"messageId": [
{
"Value": "78773889-e485-4316-89e1-69123cfa49df",
"Frequency": 0.51
},
{
"Value": "db144617-f9e5-4c52-b893-2661c8f7ab43",
"Frequency": 0.51
}
],
"originalTimestamp": [
{
"Value": "2019-08-12T05:08:30.909Z",
"Frequency": 1
}
],
"properties.category": [
{
"Value": "Demo Category",
"Frequency": 1
}
],
"properties.label": [
{
"Value": "Demo Label",
"Frequency": 1
}
],
"properties.value": [
{
"Value": "5",
"Frequency": 1
}
],
"sentAt": [
{
"Value": "2019-08-12T05:08:30.909Z",
"Frequency": 1
}
],
"type": [
{
"Value": "track",
"Frequency": 1
}
]
}
}

Contact Us

For more information on the RudderStack Events Schema API, please feel free to contact us. You can also start a conversation on our Discord channel, and we will be happy to help you.