pixel-api-spec.md

description
Detailed technical description of the RudderStack Pixel API to track and capture event data efficiently.

Pixel API

The RudderStack Pixel API allows you to track your customer event data from anywhere and route it to your desired destinations.

This API is very useful in scenarios where making a POST request is not possible. Some examples include tracking email addresses and page views where POST requests don't add or append any value.

Sending a page call to RudderStack

Parameter	Value
URL	/pixel/v1/page
Method	GET
URL Parameters:
Required	writeKey=${writeKey} anonymousId=${anonymousId}
Optional	userId=${userId} name=${page_name} context.library.name context.library.version context.platform context.locale context.userAgent context.screen.width context.screen.height context.page.path context.page.url context.page.referrer context.page.title properties.<*key1*>=${value} properties.<*key2*>=${value} properties. ...
Data Parameters	None
Success Response	Code: 200 Content: OK
Error Response	Code: 400 Bad Request Content: error string

A sample call is as shown below:

https://hosted.rudderlabs.com/pixel/v1/page?writeKey=${writeKey}&context.library.name=Rudderstack AMP SDK&context.library.version=1.0.0&context.platform=AMP&anonymousId=${anonymousId}&context.locale=${browserLanguage}&context.userAgent=${userAgent}&context.page.path=${canonicalPath}&context.page.url=${canonicalUrl}&context.page.referrer=${documentReferrer}&context.page.title=${title}&context.screen.width=${screenWidth}&context.screen.height=${screenHeight}&properties.path=${canonicalPath}&properties.url=${canonicalUrl}&properties.referrer=${documentReferrer}&properties.title=${title}&name=${pageName}

{% hint style="warning" %} For this endpoint, RudderStack expects that the basic page view properties like path, url, referrer, title be passed either with context.page.<page_basic_properties> or with properties.<page_basic_properties>. {% endhint %}

{% hint style="info" %} The dot ****(.) separated query parameters are mapped by RudderStack to a familiar page payload before sending them to the destinations. {% endhint %}

{% hint style="warning" %} Note that for this endpoint, RudderStack does not currently support overriding the integration key for sending data to selective destinations. {% endhint %}

Sending a track call to RudderStack

Parameter	Value
URL	/pixel/v1/track
Method	GET
URL Parameters:
Required	writeKey=${writeKey} anonymousId=${anonymousId} event=${event_name}
Optional	userId=${userId} context.library.name context.library.version context.platform context.locale context.userAgent context.screen.width context.screen.height context.page.path context.page.url context.page.referrer context.page.title properties.<*key1*>=${value} properties.<*key2*>=${value} properties. ...
Data Parameters	None
Success Response	Code: 200 Content: OK
Error Response	Code: 400 Bad Request Content: error string

A sample call is as shown below:

https://hosted.rudderlabs.com/pixel/v1/track?writeKey=${writeKey}&context.library.name=Rudderstack AMP SDK&context.library.version=1.0.0&context.platform=AMP&anonymousId=${anonymousId}&context.locale=${browserLanguage}&context.userAgent=${userAgent}&context.page.path=${canonicalPath}&context.page.url=${canonicalUrl}&context.page.referrer=${documentReferrer}&context.page.title=${title}&context.screen.width=${screenWidth}&context.screen.height=${screenHeight}&event=${eventName}&properties.key1=value1&properties.key2=value2

{% hint style="warning" %} For this endpoint, RudderStack expects the basic page view properties like path, url, referrer, and title to be passed with context.page.<page_basic_properties>. The event-related properties should be sent as properties.<*key1*>=${value}. {% endhint %}

{% hint style="info" %} The dot (.) separated query parameters are mapped by RudderStack to a familiar track payload before being sent to destinations. {% endhint %}

{% hint style="warning" %} Note that for this endpoint, RudderStack currently does not support overriding the integration key for sending the data to selective destination. {% endhint %}

Contact Us

To know more about the Pixel API spec, please feel free to contact us. You can also start a conversation on our Slack channel. We will be happy to help you.