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.

To use the Pixel API, create an HTTP source, connect it to your destinations, and send Pixel API requests with that source’s write key.

Prerequisites

• Create an HTTP source and connect it to a destination in your RudderStack dashboard
• 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 at the top of the Connections page in your RudderStack dashboard. must be reachable from the client that fires the pixel
• Note your source write key 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 at the top of the Connections page in your RudderStack dashboard. as the base URL for the Pixel API requests.

Track with an image pixel

In environments that cannot run JavaScript but can load images (for example static HTML notifications), point an <img> tag at a Pixel API URL. The browser issues a GET request when the image loads, which records the event—similar to legacy analytics impression pixels.

<img
  src="https://<DATA_PLANE_URL>/pixel/v1/track?writeKey=<WRITE_KEY>&anonymousId=<ANONYMOUS_ID>&event=Notification%20Impression&properties.notificationId=<NOTIFICATION_ID>"
  width="1"
  height="1"
  alt=""
/>

URL-encode query parameter values. Keep URLs within the HTTP source message size limit (32KB per call).

The write key appears in the pixel URL. Treat pixel URLs like credentials — do not expose them where users can access them beyond the intended page or email HTML. Proxy/server logs and third-party monitoring tools can also capture them — if a pixel URL is exposed, rotate the source write key.

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.