Meta Audience Network

AIR API Guide

In this section:

Prerequisite

You must have subscribed to Audience Network impression events before using the paramaeters in this Guide. Go to Client Side Integration for details.

Endpoint

https://graph.facebook.com/<app_id>/aggregate_revenue

Request Parameters

Parameters Type Description

request_id

string

Request ID generated by publisher

ecpms

vec(string)

List of encrypted CPMs (ecpms) for aggregation

access_token

string

System user token of the app

sync_api

boolean

Always set true for sync processing. Use lowercase true or false.

Sample request body

{
"request_id": "request_id",
"ecpms": ["ARE0CnURMoKOIilTFEjZGBxCofGJAFkLp-6jdkYDt7iwigbmhnNb9GEa9hIPwaqf_KautmhenM0xTDHJ4J5Qjrx_hZT0kzUIQ1TEmkGt_KKOog", "TGnURMoKOIilTFEjTEFSRssJAFkLp-6jdkYDt7iwigbmhnNb9GEa9hIPwaqf_KautmhenM0xTDHJ4J5Qjrx_hZT0kzUIQ1fsdDSD", .…, "WEdfefsdIilTFEjTEFSRssJAFkASEFWEFZsdfsdYDt7iwigbmhnNb9GEa9hIPwaqf_KautmhenM0xTDHJ4J5Qjrx_hZT0kzUIADsafdea"],
"access_token": "<access_token>",
"sync_api": true
}
}

Sample AIR Request

{
curl -XPOST 'https://graph.facebook.com/<app_id>/aggregate_revenue/' -d '{'request_id' : 'request_id_1', 'ecpms' : ['ecpm1', 'ecpm2', ... 'ecpm600'], 'access_token' : '<your_access_token>', "sync_api": true }'

}
}

Response Object

Parameters Type Description

request_id

string

Echoed back request_id received in the request

success

SuccessObject(nullable)

Details here. Only one of success / error objects will be populated

error

ErrorObject(nullable)

Details here. Only one of success / error objects will be populated

Success Object

Parameters Type Description

value

float

Dollar value corresponding to the list of eCPMs passed

accuracy

AccuracyEnum

Noise qualifier denoting the quality of revenue data

  • AccuracyEnum - one of:
  • very_good
  • good
  • average

Error Object

Parameters Type Description

reason

string

Reason why the query does not have a valid result

description

string

Detailed description of why the query did not have a valid result

no_impression_count

int(nullable)

Populated when reason is too_few_ecpms. Null otherwise. Denotes the number of ecpms that did not result in an impression

invalid_impression_count

int(nullable)

Populated when reason is too_few_ecpms. Null otherwise. Denotes the number of ecpms that were invalid or expired

Error Reasons


reason description

too_many_ecpms

There were x encrypted cpms in your request. Make sure the number of ecpms is within the limit of 3000 which resulted in impressions.

too_few_ecpms

There were x encrypted cpms in your request. Make sure the number of ecpms is more than 500 which resulted in impressions.

forbidden

You don't have the required permission to access the app's information. Use a different SystemUserToken and app_id or update the access in Business Settings.

internal_error

There was a problem processing your request. Please try again or if the problem continues contact us with your app_id and request_id.

Sample Response Objects

Sample Success Response

{
"request_id": "request_id",
"success": {
"value": 500.90,
"accuracy": "very_good"
}
}

Sample Error Response

{
"request_id": "request_id",
"error": {
"reason": "too_few_ecpms",
"description": "The number of encrypted cpms passed in the request were smaller than the specified limit. 450"
"no_impression_count": 236,
"invalid_impression_count": 1

}
}

Sample Bid Response with Encrypted CPM

{
"id": "request_id",
"seatbid": [{
"bid": [{
"id": "5952435798315929514",
"impid": "request_imp_id",
"price": 0.45860661,
"adm": "{\"type\":\"ID\",\"bid_id\":\"id\",\"placement_id\":\"placement_id\",\"resolved_placement_id\":\"resolved_placement_id\",\"sdk_version\":\"version\",\"device_id\":\"device_id\",\"template\":7,\"payload\":null,\"bid_time_token\":\"bid_token",\"encrypted_cpm\":\"ARE0CnURMoKOIilTFEjZGBxCofGJAFkLp-6jdkYDt7iwigbmhnNb9GEa9hIPwaqf_KautmhenM0xTDHJ4J5Qjrx_hZT0kzUIQ1TEmkGt_KKOog\"}",
"nurl": "https://www.facebook.com/audiencenetwork/nurl/.*",
"lurl": "https://www.facebook.com/audiencenetwork/nurl/.*,
"burl": "https://www.facebook.com/audiencenetwork/burl/.*",
"ext": {
"encrypted_cpm": "ARE0CnURMoKOIilTFEjZGBxCofGJAFkLp-6jdkYDt7iwigbmhnNb9GEa9hIPwaqf_KautmhenM0xTDHJ4J5Qjrx_hZT0kzUIQ1TEmkGt_KKOog"
}
}]
}],
"bidid": "5971462766981738161",
"cur": "USD"
}

Sample AIR Requests

Aggregation

curl -XPOST 'https://graph.facebook.com/<app_id>/aggregate_revenue/' -d '{'request_id' : 'request_id_1', 'ecpms' : ['ecpm1', 'ecpm2', ... 'ecpm600'], 'access_token' : '<your_access_token>' }'

Query

curl -XPOST 'https://graph.facebook.com/<app_id>/aggregate_revenue/' -d '{query_ids : ['query_id_1', 'query_id_2'],  'access_token' : '<your_access_token>' }'=
}'

See Also