Marketing API
Graph API Version

Ad Pixel

Reading

A Facebook pixel is a small piece of JavaScript code that an advertiser places on every page of their website. This piece of code provides a set of lightweight functionalities for sending user-specific events and event-specific custom data to Facebook. Advertisers can use the Facebook pixel to capture intent information about how people are using their website. A single Facebook pixel is added to all pages of a website, and is then used to create website custom audiences

Example

Graph API Explorer
GET /v8.0/{ads-pixel-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{ads-pixel-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{ads-pixel-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ads-pixel-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ads-pixel-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
id
numeric string

ID of the pixel

Default
automatic_matching_fields
list<enum>

Advanced matching fields which are enabled for automatic advanced matching

can_proxy
bool

can_proxy

code
string

Pixel code to be placed on the website

creation_time
datetime

Time at which the pixel was created

creator
User

The user who created this pixel

data_use_setting
enum

Setting to capture how pixel data should be used

enable_automatic_matching
bool

Represents whether automatic advanced matching is enabled for the pixel for identity matching purposes

first_party_cookie_status
enum

First party cookie status to indicate whether first party cookies can be set for this pixel

is_created_by_business
bool

Flag stands for if a pixel is created by busines

is_unavailable
bool

Whether this pixel is unavailable

last_fired_time
datetime

Time at which the pixel was last fired

name
string

Name of the pixel

owner_ad_account
AdAccount

Ad Account that owns this pixel

owner_business
Business

ID of the business that owns this pixel or null if the pixel has not been claimed by any business yet.

Edges

EdgeDescription
assigned_users

assigned_users

da_checks

A list of results after running Dynamic Ads checks on this pixel.

shared_accounts

Ad Accounts in the same business that this pixel is shared

shared_agencies

Agencies or other businesses this pixel is shared with

stats

Stats data for this pixel

Validation Rules

ErrorDescription
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read
200Permissions error
2500Error parsing graph query
368The action attempted has been deemed abusive or is otherwise disallowed
270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account

Creating

You can make a POST request to adspixels edge from the following paths:
When posting to this edge, an AdsPixel will be created.

Example

Graph API Explorer
POST /v8.0/act_<AD_ACCOUNT_ID>/adspixels HTTP/1.1
Host: graph.facebook.com

name=My+WCA+Pixel
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/adspixels',
    array (
      'name' => 'My WCA Pixel',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/act_<AD_ACCOUNT_ID>/adspixels",
    "POST",
    {
        "name": "My WCA Pixel"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My WCA Pixel");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/adspixels",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"name": @"My WCA Pixel",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adspixels"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'name="My WCA Pixel"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v8.0/act_<AD_ACCOUNT_ID>/adspixels
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
name
string

Name of the pixel

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
200Permissions error
6202More than one pixel exist for this account
6200A pixel already exists for this account
100Invalid parameter
294Managing advertisements requires an access token with the extended permission for ads_management
2633This shared login is disabled. Go to Ads Manager for more information.
You can make a POST request to adspixels edge from the following paths:
When posting to this edge, an AdsPixel will be created.

Parameters

ParameterDescription
name
string

Name of the pixel.

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to events edge from the following paths:
When posting to this edge, an AdsPixel will be created.

Example

Graph API Explorer
POST /v8.0/<PIXEL_ID>/events HTTP/1.1
Host: graph.facebook.com

data=%5B%7B%22event_name%22%3A%22PageView%22%2C%22event_time%22%3A1601525125%2C%22user_data%22%3A%7B%22fbc%22%3A%22fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890%22%2C%22fbp%22%3A%22fb.1.1558571054389.1098115397%22%2C%22em%22%3A%22309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd%22%7D%7D%5D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/<PIXEL_ID>/events',
    array (
      'data' => '[{"event_name":"PageView","event_time":1601525125,"user_data":{"fbc":"fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890","fbp":"fb.1.1558571054389.1098115397","em":"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"}}]',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<PIXEL_ID>/events",
    "POST",
    {
        "data": "[{\"event_name\":\"PageView\",\"event_time\":1601525125,\"user_data\":{\"fbc\":\"fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890\",\"fbp\":\"fb.1.1558571054389.1098115397\",\"em\":\"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd\"}}]"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("data", "[{\"event_name\":\"PageView\",\"event_time\":1601525125,\"user_data\":{\"fbc\":\"fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890\",\"fbp\":\"fb.1.1558571054389.1098115397\",\"em\":\"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd\"}}]");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<PIXEL_ID>/events",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"data": @"[{\"event_name\":\"PageView\",\"event_time\":1601525125,\"user_data\":{\"fbc\":\"fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890\",\"fbp\":\"fb.1.1558571054389.1098115397\",\"em\":\"309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd\"}}]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<PIXEL_ID>/events"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'data=[
       {
         "event_name": "PageView",
         "event_time": 1601525125,
         "user_data": {
           "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
           "fbp": "fb.1.1558571054389.1098115397",
           "em": "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"
         }
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v8.0/<PIXEL_ID>/events
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
data
list<JSON-encoded string>

data

Required
test_event_code
string

Code that is used to identify server test events

Return Type

Struct {
events_received: integer,
messages: List [
string
],
fbtrace_id: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
270This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account
105The number of parameters exceeded the maximum for this operation

Updating

You can update an AdsPixel by making a POST request to /{ads_pixel_id}.

Parameters

ParameterDescription
automatic_matching_fields
array<enum {em, fn, ln, ph, ge, zp, ct, st, country, db, external_id}>

Advanced matching fields for which automatic advanced matching should be enabled

data_use_setting
enum {EMPTY, ADVERTISING_AND_ANALYTICS, ANALYTICS_ONLY}

Setting to capture how pixel data should be used

enable_automatic_matching
boolean

Enable automatic advanced matching for the pixel for identity matching purposes

first_party_cookie_status
enum {EMPTY, FIRST_PARTY_COOKIE_ENABLED, FIRST_PARTY_COOKIE_DISABLED}

First party cookie status to indicate whether first party cookies can be set for this pixel

name
string

Name of the pixel

server_events_business_ids
array<Server Events Permitted Business ID>

server_events_business_ids

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
294Managing advertisements requires an access token with the extended permission for ads_management

Deleting

You can't perform this operation on this endpoint.