RudderStack Pixel API

This guide provides a complete reference for the RudderStack Pixel API.

Overview

The RudderStack Pixel API lets you track events and route them to your destinations using GET requests. Use this API when POST requests are not feasible — for example, when tracking email opens or page views in environments like AMP where POST requests do not add any value.

Prerequisites

• The data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. for your workspace must be accessible from your client
• Set up a source and destination in RudderStack dashboard
• Your write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. to authenticate API requests

Base URL

Use your data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. as the base URL for the Pixel API requests.

Send a page call

The page call records page views with optional context and properties.

For the page endpoint, RudderStack expects the basic page view properties (path, url, referrer, title) to be passed with context.page.{property} or with properties.{property}.

Query parameters

Parameters that use dot notation (for example, context.page.path, context.screen.width) represent nested fields in the event payload. RudderStack maps these query parameters to the standard page event structure before sending to your destinations.

Example call

https://{DATA_PLANE_URL}/pixel/v1/page?writeKey={WRITE_KEY}&anonymousId=anon-123
&context.locale=en-US
&context.userAgent=Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)
&context.page.path=%2Fhome&context.page.url=https%3A%2F%2Fexample.com%2Fhome
&context.page.referrer=https%3A%2F%2Fexample.com%2F&context.page.title=Home
&context.screen.width=1920&context.screen.height=1080
&properties.path=%2Fhome&properties.url=https%3A%2F%2Fexample.com%2Fhome
&properties.referrer=https%3A%2F%2Fexample.com%2F&properties.title=Home&name=Home%20Page

Resulting event object

The above call maps to the following event payload (excluding fields RudderStack adds automatically, like messageId, originalTimestamp, sentAt, and receivedAt):

{
  "type": "page",
  "anonymousId": "anon-123",
  "name": "Home Page",
  "properties": {
    "path": "/home",
    "url": "https://example.com/home",
    "referrer": "https://example.com/",
    "title": "Home"
  },
  "context": {
    "locale": "en-US",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "page": {
      "path": "/home",
      "url": "https://example.com/home",
      "referrer": "https://example.com/",
      "title": "Home"
    },
    "screen": {
      "width": 1920,
      "height": 1080
    }
  }
}

Response codes

Send a track call

The track call records user actions with event-specific properties.

For the track endpoint:

• Pass basic page view properties (path, url, referrer, title) with context.page.{property}.
• Pass event-related properties with properties.{key}=value.

Query parameters

Parameters that use dot notation (for example, context.page.path, properties.productId) represent nested fields in the event payload. RudderStack maps these query parameters to the standard track event structure before sending to your destinations.

Example call

https://{DATA_PLANE_URL}/pixel/v1/track?writeKey={WRITE_KEY}&anonymousId=anon-123
&context.locale=en-US
&context.userAgent=Mozilla%2F5.0%20(Windows%20NT%2010.0%3B%20Win64%3B%20x64)
&context.page.path=%2Fproduct%2Fsku-123&context.page.url=https%3A%2F%2Fexample.com%2Fproduct%2Fsku-123
&context.page.referrer=https%3A%2F%2Fexample.com%2F&context.page.title=Product%20Page
&context.screen.width=1920&context.screen.height=1080&name=Product%20Page
&event=Product%20Viewed&properties.productId=sku-123&properties.revenue=29.99

Resulting event object

The example call above maps to the following event payload (excluding fields RudderStack adds automatically, such as messageId, originalTimestamp, sentAt, and receivedAt):

{
  "type": "track",
  "anonymousId": "anon-123",
  "event": "Product Viewed",
  "name": "Product Page",
  "properties": {
    "productId": "sku-123",
    "revenue": 29.99
  },
  "context": {
    "locale": "en-US",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "page": {
      "path": "/product/sku-123",
      "url": "https://example.com/product/sku-123",
      "referrer": "https://example.com/",
      "title": "Product Page"
    },
    "screen": {
      "width": 1920,
      "height": 1080
    }
  }
}

Response codes

Limitations

The Pixel API does not support overriding the integration key to send data to selective destinations. All configured destinations receive the events.

Questions? Contact us by Email or on Slack