# 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]({{< ref "sources/event-streams/sdks/rudderstack-amp-analytics.md" >}}) where `POST` requests do not add any value.

To use the Pixel API, create an [HTTP source]({{< ref "sources/event-streams/http.md" >}}), connect it to your destinations, and send Pixel API requests with that source's write key.

## Prerequisites

- Create an [HTTP source]({{< ref "sources/event-streams/http.md" >}}) and connect it to a [destination]({{< ref "dashboard-guides/destinations.md#add-a-destination" >}}) in your RudderStack dashboard
- Your {{< glossary_tooltip "data-plane-url" >}} must be reachable from the client that fires the pixel
- Note your [source write key]({{< ref "dashboard-guides/sources.md#overview" >}}) to authenticate API requests

{{< image src="images/dashboard-guides/sources/source-information.webp" alt="Source information" >}}

## Base URL

Use your {{< glossary_tooltip "data-plane-url" >}} 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.

```html
<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]({{< ref "sources/event-streams/http.md#request-size-limits" >}}) (32KB per call).

{{< info >}}
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.
{{< /info >}}

## Send a `page` call

The [`page`]({{< ref "event-spec/standard-events/page.md" >}}) 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}`.

{{% api-method method="get" host="{DATA_PLANE_URL}" path="/pixel/v1/page" %}}

**Query parameters**

{{< query-paramsList >}}
  {{< query-params keyname="writeKey" valuename="Your source write key for authentication" keytype="Required" datatype="String" >}}
  {{< query-params keyname="anonymousId" valuename="Anonymous identifier for the user. Either `userId` or `anonymousId` is required" keytype="Required" datatype="String" >}}
  {{< query-params keyname="userId" valuename="Unique identifier for the user in your database" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="name" valuename="Name of the page being viewed" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.library.name" valuename="Name of the library or SDK (for example, `Rudderstack AMP SDK`)" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.library.version" valuename="Version of the library or SDK" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.platform" valuename="Platform context (for example, `AMP`)" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.locale" valuename="User locale (for example, browser language)" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.userAgent" valuename="User agent string" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.screen.width" valuename="Screen width in pixels" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.screen.height" valuename="Screen height in pixels" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.path" valuename="Canonical page path" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.url" valuename="Full page URL" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.referrer" valuename="Referrer URL" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.title" valuename="Page title" keytype="Optional" datatype="String" >}}
  {{< query-params keyname="properties.{key}=${value}" valuename="Custom page properties. Pass page view properties like `path`, `url`, `referrer`, and `title` either with `context.page.{property}` or with `properties.{property}`" keytype="Optional" datatype="String" >}}
{{< /query-paramsList >}}

{{< info >}}
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`]({{< ref "event-spec/standard-events/page.md" >}}) event structure before sending to your destinations.
{{< /info >}}

**Example call**

```text
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`):

```json
{
  "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**

| Code | Description |
| :--- | :--- | 
| `200 OK` | Request processed successfully |
| `400 Bad Request` | Invalid request or missing required parameters |

## Send a `track` call

The [`track`]({{< ref "event-spec/standard-events/track.md" >}}) 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`.

{{% api-method method="get" host="{DATA_PLANE_URL}" path="/pixel/v1/track" %}}

**Query parameters**

{{< query-paramsList >}}
  {{< query-params keyname="writeKey" valuename="Your source write key for authentication." keytype="Required" datatype="String" >}}
  {{< query-params keyname="anonymousId" valuename="Anonymous identifier for the user. Either `userId` or `anonymousId` is required." keytype="Required" datatype="String" >}}
  {{< query-params keyname="event" valuename="Name of the event being tracked." keytype="Required" datatype="String" >}}
  {{< query-params keyname="userId" valuename="Unique identifier for the user in your database." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="name" valuename="Page name for context." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.library.name" valuename="Name of the library or SDK (for example, `Rudderstack AMP SDK`)." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.library.version" valuename="Version of the library or SDK." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.platform" valuename="Platform context (for example, `AMP`)." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.locale" valuename="User locale (for example, browser language)." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.userAgent" valuename="User agent string." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.screen.width" valuename="Screen width in pixels." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.screen.height" valuename="Screen height in pixels." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.path" valuename="Canonical page path." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.url" valuename="Full page URL." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.referrer" valuename="Referrer URL." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="context.page.title" valuename="Page title." keytype="Optional" datatype="String" >}}
  {{< query-params keyname="properties.{key}" valuename="Custom event properties. Use `context.page.{property}` for page view properties; use `properties.{key}=value` for event-specific properties." keytype="Optional" datatype="String" >}}
{{< /query-paramsList >}}

{{< info >}}
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`]({{< ref "event-spec/standard-events/track.md" >}}) event structure before sending to your destinations.
{{< /info >}}

**Example call**

```text
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`):

```json
{
  "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**

| Code | Description |
| :--- | :--- | 
| `200 OK` | Request processed successfully |
| `400 Bad Request` | Invalid request or missing required parameters |

## Limitations

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

<br />