# 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            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Optional            | <p><code>context.library.name</code></p><p><code>context.library.version</code></p><p><code>context.platform</code></p><p><code>context.locale</code></p><p><code>context.userAgent</code></p><p><code>context.screen.width</code></p><p><code>context.screen.height</code></p><p><code>context.page.path</code></p><p><code>context.page.url</code></p><p><code>context.page.referrer</code></p><p><code>context.page.title</code></p><p><code>properties. ...</code></p> |
| Data Parameters     | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Success Response    | <ul><li>Code: <code>200</code></li><li>Content: <code>OK</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                  |
| Error Response      | <ul><li>Code: <code>400 Bad Request</code></li><li>Content: <code>error string</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                            |

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}
```

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>`.

The dot (`.`) separated query parameters are mapped by RudderStack to a familiar [`page`](https://rudderstack.com/docs/rudderstack-api/http-api#81-page-payload) payload before sending them to the destinations.

Note that for this endpoint, RudderStack does not currently support overriding the `integration` key for sending data to selective destinations.

## Sending a `track` call to RudderStack

| Parameter           | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL                 | *`/pixel/v1/track`*                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Method              | `GET`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **URL Parameters:** |                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Required            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Optional            | <p><code>context.library.name</code></p><p><code>context.library.version</code></p><p><code>context.platform</code></p><p><code>context.locale</code></p><p><code>context.userAgent</code></p><p><code>context.screen.width</code></p><p><code>context.screen.height</code></p><p><code>context.page.path</code></p><p><code>context.page.url</code></p><p><code>context.page.referrer</code></p><p><code>context.page.title</code></p><p><code>properties. ...</code></p> |
| Data Parameters     | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Success Response    | <ul><li>Code: <code>200</code></li><li>Content: <code>OK</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                                                  |
| Error Response      | <ul><li>Code: <code>400 Bad Request</code></li><li>Content: <code>error string</code></li></ul>                                                                                                                                                                                                                                                                                                                                                                            |

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
```

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}`.

The dot (`.`) separated query parameters are mapped by RudderStack to a familiar [`track`](https://rudderstack.com/docs/rudderstack-api/http-api#72-track-usage) payload before being sent to destinations.

Note that for this endpoint, RudderStack currently does not support overriding the `integration` key for sending the data to selective destination.

## Contact Us

To know more about the Pixel API spec, please feel free to [contact us](mailto:%20docs@rudderstack.com). You can also start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community. We will be happy to help you.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rudderlabs.gitbook.io/rudderlabs-1/docs/rudderstack-api/pixel-api-spec.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.