Audience Network

AIR API Guide

Updated: Jun 28, 2021
Copy for LLM
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