Provides a programmatic way to query reporting data from Facebook Attribution, including campaigns, sources and conversion events.
This API is available as an open beta and is subject to change.
If you don't have an app in Business Manager, you need to create one. To start, your app will be placed in Dev Tier with limited access to only the assets within your business.
To query the Attribution API, you must generate an access token that includes the following permissions: business_management
, ads_read
, and attribution_read
.
business_management
permission. The Business Manager that grants business_management
permission to the app is the one where the app is added as an asset. You can only add an app to one Business Manager.ads_read
permission to read advertising-related data.attribution_read
permission to read Attribution data. This can be for lines of business you own, or lines of businesses you have been granted access to by the owner.When you’re ready to publish your app, you’ll need to undergo App Review. Your request must include business_management
, ads_read
, attribution_read
, and Ads Management Standard Access.
Note that approval for this API requires business verification.
A good starting point for fetching any data about a business is from the business ID. You can fetch the name and ID of the business, along with the names and IDs of all the business units associated with the business.
https://graph.facebook.com/<VERSION>/<BUSINESS_ID>? fields=id,name,business_units{id,name} &access_token=<TOKEN>
Note: Business units are referred to as lines of business in the Facebook Attribution UI.
The field{subfield1,subfield2}
syntax appears often in query results:
{ "id": "<BUSINESS_ID>", "name": "Business 1", "business_units": { "data": [ { "id": "<BUSINESS_UNIT_ID>", "name": "Business Unit 1" }, ... { "id": "<BUSINESS_UNIT_ID>", "name": "Business Unit 2" } ], ... } }
You can also write this query as shown below:
https://graph.facebook.com/<VERSION>/? fields=id,name,business_units{id,name} &ids=<BUSINESS_ID> &access_token=<token>
In this example, <BUSINESS_ID>
is a query parameter instead of a path parameter. This is useful when you query several business units at once:
{ "<BUSINESS_ID>": { "id": "<BUSINESS_ID>", "name": "Business 1", "business_units": { "data": [ { "id": "<BUSINESS_UNIT_ID>", "name": "Business Unit 1" }, ... { "id": "<BUSINESS_UNIT_ID>", "name": "Business Unit 2" } ], ... } }
Note: Business units are referred to as lines of business in the Facebook Attribution UI.
The following queries use a sample business unit ID, <BUSINESS_UNIT_ID>
. From this business unit ID, we can get a list of campaigns, conversion events, ad platforms, and external import files associated with the business unit.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=ad_platforms .order_by([{"direction":"asc","field":"name"}]) .filter_by({"is_archived":false}) .limit(3) .count(1) .summary(1) {connection_details,external_import_file,connection_type,created_date,custom_tags,id,is_archived,last_modified_by{id,name},last_modified_date,live_status,name,platform_type,setup_progress} &access_token=<TOKEN>
You get a Response 200 OK
and results that look like this:
{ "<BUSINESS_UNIT_ID>": { "ad_platforms": { "data": [ { "external_import_file": { "data": [ { "id": "<EXTERNAL_IMPORT_FILE_ID>", "original_file_name": "template.csv" }, ... ] }, "connection_type": "<CONNECTION_TYPE>", "created_date": "2019-01-15T00:43:06+0000", "custom_tags": { "data": [ { "click_tag": "}", "view_tag": ";" } ] }, "id": "<AD_PLATFORM_ID>", "is_archived": false, "last_modified_by": { "id": "<USER_ID>", "name": "User Name" }, "last_modified_date": "2019-08-08T17:44:15+0000", "live_status": "inactive", "name": "Platform Name", "platform_type": "<PLATFORM_TYPE>", "setup_progress": "tagging_setup" }, ... ] } } }
A list of fields is below:
business
- Business associated with this business unit ID <Business>
creation_time
- Creation time for this business unit <string>
name
- Name of the business unit <string>
ad_accounts
- Ad accounts associated with the business unit <AdAccount>
assigned_users
- List of assigned users to the business unit <BusinessUser>
. This query needs business unit as a parameter. Example query would be:https://graph.facebook.com/<VERSION>/<BUSINESS_UNIT_ID>/assigned_users? business=<BUSINESS_ID> &access_token=<TOKEN>
assigned_partners
- List of assigned partners to the business unit . This query needs business unit as a parameter. Example query would be:https://graph.facebook.com/<VERSION>/<BUSINESS_UNIT_ID>/assigned_partners? business=<BUSINESS_ID> &access_token=<TOKEN>
currency
- Default currency for the business unittime_zone
- Default time zone for the business unitexternal_import_file
- List of imported files for external attribution datacustom_breakdowns
- Custom grouping of campaignsreports
- List of reports for the business unitFor each business unit, we can obtain a list of potential issues through the diagnostics endpoint.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=diagnostics{additional_data,id,last_action_time,last_fired_time,type,status} &access_token=<token>
You should get this response Response 200 OK
and these results:
{ "<BUSINESS_UNIT_ID>": { "diagnostics": { "data": [ { "id": "<DIAGNOSTIC_ID>", "last_action_time": "2019-09-12T20:53:51+0000", "last_fired_time": "2018-10-15T23:41:22+0000", "type": "unassigned_landing_page_pixel", "status": "resolved" }, ... { "id": "<DIAGNOSTIC_ID>", "last_fired_time": "2019-06-18T03:01:15+0000", "type": "unassigned_ad_account", "status": "resolved" } ] }, "id": "<BUSINESS_UNIT_ID>" }
The values for type
include:
Value | Description |
---|---|
| One or more of your ads link to an app store. This could cause there to be a high number of clicks but a low number of reported visits, and may result in under-crediting non-Facebook sources. This only impacts your Attribution reporting. |
| One or more of your ads use links from a URL shortener. This could prevent your pixel from detecting any Urchin Tracking Module, or UTM, tags or referring domains from your ad URL, which will cause visits from that ad URL to be reported as Direct. This only impacts your Attribution reporting. |
| There are significantly fewer visits for some of your ad URLs than clicks on the ad. This usually indicates a problem with the ad URL or the pixel on the landing page, and may result in over-crediting clicks on ads and under-crediting other visits to websites. This only impacts your Attribution reporting. |
| You are receiving impressions and clicks from your Facebook ads, but no website visits from your pixel. This could mean that your landing pages do not have a pixel on them, which will prevent visits from being received. This may cause an increase in conversions attributed to Direct. This only impacts your Attribution reporting. |
| The ad account isn't assigned to a business unit. Any ad campaigns associated with this ad account aren't currently included in your Attribution reporting. Once you add this ad account your business unit, you'll be able to see which conversions happened as a result of these campaigns. |
| Your business unit contains an ad account with one or more pixels that are not assigned to the business unit. This means that you are receiving Facebook campaign data from the ad account, but not visits from the pixel for non-Facebook sources. This will result in lower than expected visit counts. This only impacts your Attribution reporting. |
Values for status
include:
active
resolved
snoozed
ignored
Note: AdditionalData
contains information about the diagnostic event that fired, such as a list of affected pixels, ad accounts, URLs and so on.
Through the Attribution API, you can query a wide range of metrics. Some metrics, such as basic stats, are returned by default and not associated with any attribution model. For example, you get these metrics when you query an ad object, such as an ad campaign.
Metric | Metric Name in UI |
---|---|
| Cost per 1,000 Impressions
Value returned in 1/100,000,000 of the business unit's currency
|
| Cost per Click
Value returned in 1/100,000,000 of the business unit's currency
|
| Cost per Visit
Value returned in 1/100,000,000 of the business unit's currency
|
| Cost
Value returned in 1/100,000,000 of the business unit's currency
|
| Click-Through Rate, or CTR |
| Clicks |
| Impressions |
| Visits |
When querying for metrics, you'll need to provide an additional argument called metric_scope
. This argument accepts an object that defines the context for which metrics will be returned.
The following properties can be defined for metric_scope
:
Property | Description |
---|---|
| The exact date range to query over. This property is only required if the value provided for |
| Filters that can be used to narrow the results based on attribution window or visit configuration |
boolean | Default value: Determines if the prior time periods data should also be included in the query. For example, if your time period is |
| Default value: Determines the dates that the query is run for. |
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=campaigns .metric_scope({"time_period":"last_thirty_days"}) {id,created_date,name,report_clicks,report_impressions,report_visits} &access_token=<TOKEN>
You get a Response 200 OK
and these results:
{ "<BUSINESS_UNIT_ID>": { "campaigns": { "data": [ { "id": "<CAMPAIGN_ID_1>", "created_date": "2018-04-12T14:34:26+0000", "name": "Campaign Name 1", "report_clicks": 12, "report_impressions": 1801, "report_visits": 8 }, { "id": "<CAMPAIGN_ID_2>", "created_date": "2018-04-12T14:34:46+0000", "name": "Campaign Name 2", "report_clicks": 10455, "report_impressions": 2120593, "report_visits": 8382 }, ... ], ... }, "id": "<BUSINESS_UNIT_ID>" } }
Sources are where people saw or clicked your ads, or came to your website from. For more information, see Ads Help, Analyze conversion performance.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=sources .metric_scope({"time_period":"yesterday"}) {id,created_date,name,report_clicks,report_impressions,report_visits} &access_token=<TOKEN>
The response includes Response 200 OK
and:
{ "<BUSINESS_UNIT_ID>": { "sources": { "data": [ { "id": "<SOURCE_ID_1>", "created_date": "2013-12-18T19:55:05+0000", "name": "Facebook", "report_clicks": 5, "report_impressions": 164, "report_visits": 3 }, { "id": "<SOURCE_ID_2>", "created_date": "2018-12-03T21:13:01+0000", "name": "untracked", "report_clicks": 0, "report_impressions": 0, "report_visits": 265 }, { "id": "<SOURCE_ID_3>", "created_date": "2018-12-05T12:52:46+0000", "name": "referral_google", "report_clicks": 0, "report_impressions": 0, "report_visits": 0 }, ... ], }, "id": "<BUSINESS_UNIT_ID>" } }
In the example above, the sources with the prefix referral_
are organic sources while untracked
is the alias for direct visits.
You can use a regular expression to group campaigns together for reporting. Your expression should be a standard CONTAINS
statement. Additionally, you can get custom breakdowns through the custom_breakdowns
field for each business unit.
https://graph.facebook.com/<VERSION>? ids=<BUSINESS_UNIT_ID> &fields=custom_breakdowns{name,dimension_type,match_type,custom_breakdown_rulesets} &access_token=<TOKEN>
The response includes Response 200 OK
and:
{ "<BUSINESS_UNIT_ID>": { "custom_breakdowns": { "data": [ { "name": "Breakdown", "dimension_type": "campaign", "match_type": "contains", "custom_breakdown_rulesets": { "data": [ { "name": "__special__ungrouped__", "id": "<CUSTOM_BREAKDOWN_RULESET_ID>" }, { "name": "__special__overlap__", "id": "<CUSTOM_BREAKDOWN_RULESET_ID>" }, { "name": "Grouping", "id": "<CUSTOM_BREAKDOWN_RULESET_ID>" } ] }, "id": "<CUSTOM_BREAKDOWN_ID>" }, ... ] } } }
For each business unit, you can query a list of conversion events such as Website Purchases, Website Adds to Cart, and so on.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=conversion_events{id,name} &access_token=<TOKEN>
The response looks like this and includes Response 200 OK
:
{ "<BUSINESS_UNIT_ID>": { "conversion_events": { "data": [ { "name": "Website Purchases", "id": "<CONVERSION_EVENT_ID>" }, ... { "name": "Website Adds to Cart", "id": "<CONVERSION_EVENT_ID>" } ] }, "id": "<BUSINESS_UNIT_ID>" } }
You can also get the total number of conversions per conversion event through this endpoint.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=conversion_events .filter_by({"is_archived":false}) .limit(1000) .count(1) .summary(1) .metric_scope({"time_period":"today"}) {total_conversions,name} &access_token=<TOKEN>
The response includes Response 200 OK
and:
{ "<BUSINESS_UNIT_ID>": { "conversion_events": { "data": [ { "total_conversions": 197, "name": "Website Purchases", "id": "<CONVERSION_EVENT_ID>" }, ... { "total_conversions": 0, "name": "Website Adds to Cart", "id": "<CONVERSION_EVENT_ID>" } ], "summary": { "count": 23 } }, "id": "<BUSINESS_UNIT_ID>" } }
You can get conversion paths data by querying on the conversion event ID. Your request requires a few additional parameters.
Parameter | Description |
---|---|
| The time period for which we want the conversion paths, for example: |
| The number of seconds to look back for clicks, attribution window |
| The number of seconds to look back for impressions, attribution window |
https://graph.facebook.com/<VERSION>/? ids=<CONVERSION_EVENT_ID> &fields=conversion_paths .time_period(last_thirty_days) .click_lookback_window(2419200) .view_lookback_window(2419200) .limit(10) &access_token=<TOKEN>
The results look like this:
{ "<CONVERSION_EVENT_ID>": { "conversion_paths": { "data": [ { "conversion_path": [ { "publisher_id": <SOURCE_ID>, "publisher_name": "untracked", "count": 1 } ], "conversions": 58676933 }, ... } ] } }
You can also query metrics for events that occur accross multiple devices such as desktop or mobile app from a conversion event.
https://graph.facebook.com/<VERSION>/? ids=<CONVERSION_EVENT_ID> &fields=cross_device_insights .limit(6) .count(1) .summary(1) .metric_scope({ "filters":{ "click_lookback_window":"2419200", "view_lookback_window":"2419200", }, "time_period":"last_thirty_days" }) {alias,id,name,contributor_device_path_type,conversion_device_type,metric_conversions,metric_desktop_contributors,metric_mobile_contributors}
The response looks like this:
{ "<CONVERSION_EVENT_ID>": { "cross_device_insights": { "data": [ { "contributor_device_path_type": 1, "conversion_device_type": 1, "metric_conversions": 86172450, "metric_desktop_contributors": 309295852, "metric_mobile_contributors": 0 }, { "contributor_device_path_type": 1, "conversion_device_type": 2, "metric_conversions": 2793409, "metric_desktop_contributors": 7901510, "metric_mobile_contributors": 0 }, { "contributor_device_path_type": 2, "conversion_device_type": 1, "metric_conversions": 87680843, "metric_desktop_contributors": 0, "metric_mobile_contributors": 661044484 }, { "contributor_device_path_type": 2, "conversion_device_type": 2, "metric_conversions": 86756147, "metric_desktop_contributors": 0, "metric_mobile_contributors": 854873830 }, { "contributor_device_path_type": 3, "conversion_device_type": 1, "metric_conversions": 156495682, "metric_desktop_contributors": 1398688950, "metric_mobile_contributors": 2192749520 }, { "contributor_device_path_type": 3, "conversion_device_type": 2, "metric_conversions": 14926552, "metric_desktop_contributors": 86357391, "metric_mobile_contributors": 255484632 } ] }, "id": "<CONVERSION_EVENT_ID>" } }
The following are values you can get in the response for contributor_device_path_type
:
Name | Value | Note |
---|---|---|
|
| Unable to determine the type of contributing device(s) |
|
| |
|
| |
|
| Contributing touchpoint(s) occurred on both desktop and mobile devices |
And the following are values you can get in the response for conversion_device_type
:
Name | Value | Note |
---|---|---|
|
| Unable to determine the device type a conversion occurred on |
|
| |
|
|
Attribution-related metrics can also be obtained through the conversion event endpoint. These depend on an attribution model and the type of the conversion event.
Metrics related to attribution depend on the type of attribution model you choose. The example here uses the last touch attribution model with a 28-day click and visit, 1-day impression attribution window.
We specify this in two places — the fields that we retrieve correspond to the last touch attribution model, and the configuration in the metric scope parameter determines the click and visit attribution window.
https://graph.facebook.com/<VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=conversion_events .filter_by({"ids":["<CONVERSION_EVENT_ID>"]}) .metric_scope({ "filters":{ "click_lookback_window":"2419200", "view_lookback_window":"86400", "visit_configuration":"include_paid_organic" }, "time_period":"last_thirty_days" }) {id,name,cost_per_1k_impressions,cost_per_click,cost_per_visit,net_media_cost,report_click_through_rate,report_clicks,report_impressions,report_visits,last_touch_convs,last_touch_convs_per_1k_impress,last_touch_convs_per_click,last_touch_convs_per_visit,last_touch_cpa,last_touch_revenue,last_touch_roas,total_conversions, metrics_breakdown .dimensions(["source_channel"]) {source_channel,cost_per_1k_impressions,cost_per_click,cost_per_visit,net_media_cost,report_click_through_rate,report_clicks,report_impressions,report_visits,last_touch_convs,last_touch_convs_per_1k_impress,last_touch_convs_per_click,last_touch_convs_per_visit,last_touch_cpa,last_touch_revenue,last_touch_roas} } &access_token=<TOKEN>
The query has three parts:
?ids<BUSINESS_ID>=&fields=conversion_events.filter_by({"ids":["<CONVERSION_EVENT_ID>"]})
metric_scope({"filters":{"click_lookback_window":"2419200","view_lookback_window":"86400"...})
{alias,id,name...{source_channel,cost_per_1k_impressions,cost_per_click}}
Metrics that use an attribution model are pre-pended with the name of the model used to calculate their result. The following list of attribution model prefixes and table of metric suffixes can be used to determine attribution model metrics names. For example, the metric name for last touch conversions is a combination of the model prefix last_touch
and the metric suffix _convs
resulting in last_touch_convs
.
data_driven
even_credit
last_touch
last_click
first_click
first_touch
positional_30fl
positional_40fl
time_decay_1day
time_decay_7day
Metric Name | Metric Suffix |
---|---|
Conversions |
|
Conversions per 1,000 Impressions |
|
Click Conversion Rate |
|
Visit Conversion Rate |
|
Cost per Conversion
Value returned in 1/100,000,000 of the business unit's currency
|
|
Conversion Value |
|
Return on Ad Spend |
|
For more information on attribution models, see Ads Help, About attribution models
There are several breakdowns you can apply to your results. For example, you can break your results down by source_channel
. Refer to the Source Channel reference to see all source channels.
The following are the metrics that may be returned under the breakdown:
Metric Name | Metric |
---|---|
Cost per 1,000 Impressions
Value returned in 1/100,000,000 of the business unit's currency
|
|
Cost per Click
Value returned in 1/100,000,000 of the business unit's currency
|
|
Cost per Visit
Value returned in 1/100,000,000 of the business unit's currency
|
|
Conversions
Based on attribution model
|
|
Conversions per 1,000 Impressions
Based on attribution model
|
|
Click Conversion Rate
Based on attribution model
|
|
Cost Per Conversion
Based on attribution model, value returned in 1/100,000,000 of the business unit's currency
|
|
Conversion Value
Based on attribution model
|
|
Return on Ad Spend
Based on attribution model
|
|
Cost
Value returned in 1/100,000,000 of the business unit's currency
|
|
Click-Through Rate, or CTR |
|
Clicks |
|
Impressions |
|
Visits |
|
For more information about these metrics, see Ads Help, Glossary of Facebook Attribution metrics.
{ "<BUSINESS_UNIT_ID>": { "conversion_events": { "data": [ { "id": "11027206182902", "name": "Website Purchases", "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 5945, "last_touch_convs": 0, "last_touch_convs_per_visit": 0, "last_touch_revenue": 0, "total_conversions": 4, "metrics_breakdown": { "data": [ { "source_channel": 3, "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 1795, "last_touch_convs": 0, "last_touch_revenue": 0 }, { "source_channel": 0, "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 2469, "last_touch_convs": 0, "last_touch_revenue": 0 }, { "source_channel": 1, "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 1681, "last_touch_convs": 0, "last_touch_revenue": 0 } ] } } ] }, "id": "<BUSINESS_UNIT_ID>" } }
Different types of attribution models include:
data_driven
even_credit
last_touch
last_click
first_click
first_touch
positional_30fl
positional_40fl
time_decay_1day
time_decay_7day
For descriptions and definitions of each model, see Ads Help, About attribution models.
Depending on the attribution model, conversion event and attribution window, you can further define when a channel or source should get credit for an attribution. See All Channels.
Attribution results require the metric scope parameter similar to the block above. A sample metric scope parameter is shown below.
metric_scope({ "filters":{ "click_lookback_window":"2419200", "view_lookback_window":"86400", "visit_configuration":"include_paid_organic" }, "should_include_prior_period":false, "time_period":"last_thirty_days" })
For example, this query enforces a metric scope on the publishers with a click window of 28 days, or 2419200 seconds, an impression window of 1 day, or 86400 seconds, and a time period of the last 30 days. Refer to the table of attribution windows in the reference section to look up the attribution windows in seconds.
Allowed attribution windows for attribution metrics include:
Additionally, we can also specify metrics breakdown by granularity, such as day, week, month, lifetime. Do this to get basic metrics in a more granular fashion.
https://graph.facebook.com/<VERSION>/? ids=<CONVERSION_EVENT_ID> &fields=sources .limit(2) .count(1) .summary(1) .metric_scope({ "filters":{ "click_lookback_window":"2419200", "view_lookback_window":"86400" }, "time_period":"last_thirty_days" }) {id,name,cost_per_visit,net_media_cost,report_clicks,report_impressions,report_visits,last_touch_convs,last_touch_revenue, metrics_breakdown .granularity(day) .limit(2) {timestamp,report_clicks,report_impressions,report_visits} } &access_token=<TOKEN>
The response looks like this:
{ "<BUSINESS_UNIT_ID>": { "sources": { "data": [ { "id": "<SOURCE_ID>", "name": "referral_facebook", "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 1598, "last_touch_convs": 0, "last_touch_revenue": 0, "metrics_breakdown": { "data": [ { "timestamp": 1569654000, "report_clicks": 0, "report_impressions": 0, "report_visits": 17 }, { "timestamp": 1569567600, "report_clicks": 0, "report_impressions": 0, "report_visits": 23 } ], "paging": { ... } } }, { "id": "<SOURCE_ID>", "name": "untracked", "cost_per_visit": 0, "net_media_cost": 0, "report_clicks": 0, "report_impressions": 0, "report_visits": 2469, "last_touch_convs": 0, "last_touch_revenue": 0, "metrics_breakdown": { "data": [ { "timestamp": 1569654000, "report_clicks": 0, "report_impressions": 0, "report_visits": 5 }, { "timestamp": 1569567600, "report_clicks": 0, "report_impressions": 0, "report_visits": 2 } ], "paging": { ... } }, ... ], ... "summary": { "count": 8, "metric_date_range": { "date_range": { "begin_date": "2019-09-22T00:00:00-0700", "end_date": "2019-10-22T00:00:00-0700", "time_zone": "America/Los_Angeles" }, "prior_period_date_range": { "begin_date": "2019-08-23T00:00:00-0700", "end_date": "2019-09-22T00:00:00-0700", "time_zone": "America/Los_Angeles" } } } }, "id": "<BUSINESS_UNIT_ID>" } }
The example also shows how aggregate operations like limit, count, and summary can be applied on such a query.
For each business unit, you can query a list of reports that have already been created from the Attribution UI. Currently, you cannot create or edit reports through the API.
https://graph.facebook.com/<API_VERSION>/? ids=<BUSINESS_UNIT_ID> &fields=reports{id,name,created_date}
The response includes Response 200 OK and:
{ "<BUSINESS_UNIT_ID>": { "reports": { "data": [ { "id": "<REPORT_ID>", "name": "Report name", "created_date": "2018-09-07T16:32:34+0000" }, ... ] } "id": "<BUSINESS_UNIT_ID>" } }
Each report is associated with a report schedule and one or more report runs. These can be queried using the report ID.
https://graph.facebook.com/<VERSION>/? ids=<REPORT_ID> &fields=report_s
The response includes Response 200 OK and:
{ "<REPORT_ID>": { "report_schedules": { "data": [ { "id": "<REPORT_SCHEDULE_ID>", "recurrence_type": "weekly", "date_range": { "begin_date": "2019-11-25T15:15:20-0800", "end_date": "2020-02-17T15:15:20-0800", "time_zone": "America/Los_Angeles" }, "is_active": true } ] }, "id": "<REPORT_ID>" } }
Recurrence type can assume the following values:
* once
* daily
* weekly
* monthly
Each report can be generated multiple times given a report schedule. These can be queried by:
https://graph.facebook.com/<API_VERSION>/? ids=<REPORT_ID> &fields=report_runs{id,name,file_format,status}
The response includes Response 200 OK and:
{ "<REPORT_ID>": { "report_runs": { "data": [ { "id": "<REPORT_RUN_ID>", "name": "Weekly Performance Report", "file_format": "xlsx", "status": "completed" } ... ] }, "id": "<REPORT_ID>" } }
You can download any of the report runs above by:
https://graph.facebook.com/<API_VERSION>/? ids=<REPORT_RUN_ID> &fields=id,name,data &filename=<DOWNLOAD_FILE_NAME>
The response includes Response 200 OK and:
{ "<REPORT_RUN_ID>": { "id": "<REPORT_RUN_ID>", "name": "Weekly Performance Report", "data": { "data": [ { "url": "<DOWNLOAD_URL>" } ] } } }
The url
field contains a link to download the report.
Field | Description |
---|---|
| ID of the report. |
| Compression type of the report file. |
| Date when report was created. |
| Date when report was created. |
| If the report includes deprecated features, this includes all reasons that it is deprecated. |
| Report file format. |
| Date when the report was last edited. |
| Last report run for this report. |
| List of report runs for the report. |
| List of report schedules for the report. |
| Name of the report. |
Field | Description |
---|---|
| ID of the report run. |
| Date when the report run was completed. |
| Compression type of report file. |
| Date when report run was created. |
| Link to download the report run. Requires the query parameter “filename”. |
| If the report run includes deprecated features, this includes all reasons that it is deprecated. |
| Numeric code representing error. |
| Report file format. |
| Date on which the report was last edited. |
| Name of the report run. |
| Report associated with the report run. |
| Report schedule associated with the report run. |
| Current status of the report run. |
| Version number of the report. |
Field | Description |
---|---|
| ID of the report schedule. |
| Date when the report schedule was created. |
| Start and end date for the report schedule to run. |
| Specifies if the report schedule is active. |
| Date on which the report schedule was last edited. |
| Type for the frequency at which an event is scheduled to occur. |
| Report associated with the report schedule. |
Note: All time periods except for DATE_RANGE
are relative to today and do not include today's data.
ALL_DATES
DATE_RANGE
LAST_FOURTEEN_DAYS
LAST_MONTH
LAST_NINETY_DAYS
LAST_QUARTER
LAST_SEVEN_DAYS
LAST_SIXTY_DAYS
LAST_THIRTY_DAYS
LAST_YEAR
THIS_MONTH_WHOLE_DAYS
YESTERDAY
Property | Description |
---|---|
int | The begin date of the desired date range in Unix time. |
int | The end date of the desired date range in Unix time. |
string | The name of the time zone being queried over. Example: |
| The value is required to be |
Property | Description |
---|---|
string | String representation of the click window from the desired attribution window |
string | String representation of the impression window from the desired attribution window |
| Allows adjustment of how visits are considered when calculating attribution. |
Property | Description |
---|---|
| Credit all visits normally. |
| Credit direct visits and prefer paid touchpoints over organic touchpoints. |
| Do not credit direct visits and prefer paid touchpoints over organic touchpoints. |
| Only credit paid and organic touchpoints. If there are no paid or organic touchpoints before a conversion, then the conversion will be attributed to direct. |
| Do not credit visits. |
All attribution windows are communicated to the API in seconds as strings. While there are two types of attribution windows, our system only accepts a subset of the total possible number of windows.
Attribution Window | Click Window Value | View Window Value |
---|---|---|
1-day click and visit, 1-day impression | 86400 | 86400 |
7-day click and visit, 4-hour impression | 604800 | 14400 |
7-day click and visit, 1-day impression | 604800 | 86400 |
7-day click and visit, 7-day impression | 604800 | 604800 |
14-day click and visit, no impressions | 1209600 | 0 |
14-day click and visit, 1-day impression | 1209600 | 86400 |
14-day click and visit, 14-day impression | 1209600 | 1209600 |
28-day click and visit, no impressions | 2419200 | 0 |
28-day click and visit, 4-hour impression | 2419200 | 14400 |
28-day click and visit, 1-day impression | 2419200 | 86400 |
28-day click and visit, 7-day impression | 2419200 | 604800 |
28-day click and visit, 14-day impression | 2419200 | 1209600 |
28-day click and visit, 28-day impression | 2419200 | 2419200 |
30-day click and visit, 1-day impression | 2592000 | 86400 |
30-day click and visit, 30-day impression | 2592000 | 2592000 |
90-day click and visit, 30-day impression | 7776000 | 2592000 |
90-day click and visit, 90-day impression | 7776000 | 7776000 |
Name | Enum Name | Enum Value |
---|---|---|
Direct |
| 0 |
Organic |
| 1 |
Paid Facebook |
| 2 |
Paid Third Party |
| 3 |
Paid Combination of Paid Facebook and Paid Third Party |
| 4 |