Attribution API

Overview

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.

Before You Start

Create an App

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.

Required Permissions

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: A Business Manager admin needs to log into the app to grant 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: Your app needs ads_read permission to read advertising-related data.
• attribution_read: Your app needs 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.

Publishing Your App

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.

Business

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"
        }
      ],
     ...
  }
}

Business Units

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"
        },
        ...
      ]
    }
  }
}

Fields for Business Unit

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 unit
• time_zone - Default time zone for the business unit
• external_import_file - List of imported files for external attribution data
• custom_breakdowns - Custom grouping of campaigns
• reports - List of reports for the business unit

Diagnostics

For 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:

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.

General Metrics

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 Scope

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:

Basic Stats for Campaigns

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

Basic Stats for Sources

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.

Custom Breakdowns

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>"
        },
        ...
      ]
    }
  }
}

Conversion Events

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

Conversion Paths

You can get conversion paths data by querying on the conversion event ID. Your request requires a few additional parameters.

Allowed attribution windows for Conversion Paths:

• 7-day click and visit, 4-hour impression
• 28-day click and visit, 4-hour impression
• 28-day click and visit, 1-day impression
• 28-day click and visit, 28-day impression
• 90-day click and visit, 90-day impression

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
        },
        ...
      }
    ]
  }
}

Cross-Device Insights

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

Allowed attribution windows for Cross Device Insights:

• 7-day click and visit, 4-hour impression
• 28-day click and visit, 4-hour impression
• 28-day click and visit, 1-day impression
• 28-day click and visit, 28-day impression
• 90-day click and visit, 90-day impression

The following are values you can get in the response for contributor_device_path_type:

And the following are values you can get in the response for conversion_device_type:

Attribution Results

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.

Conversion Metrics by Attribution Model

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:

• The business unit ID and the conversion event ID — ?ids<BUSINESS_ID>=&fields=conversion_events.filter_by({"ids":["<CONVERSION_EVENT_ID>"]})
• Metric scope which we require for Attribution results — metric_scope({"filters":{"click_lookback_window":"2419200","view_lookback_window":"86400"...})
• A list of fields to get for the query — such as {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

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:

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.

Sources Credited for a Conversion Event

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:

• 1-day click and visit, 1-day impression
• 7-day click and visit, 4-hour impression
• 7-day click and visit, 1-day impression
• 7-day click and visit, 7-day impression
• 28-day click and visit, 0-day impression
• 28-day click and visit, 4-hour impression
• 28-day click and visit, 1-day impression
• 28-day click and visit, 7-day impression
• 28-day click and visit, 14-day impression
• 28-day click and visit, 28-day impression
• 14-day click and visit, 0-day impression
• 14-day click and visit, 1-day impression
• 14-day click and visit, 14-day impression
• 30-day click and visit, 30-day impression
• 30-day click and visit, 1-day impression
• 90-day click and visit, 30-day impression
• 90-day click and visit, 90-day impression

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.

Attribution Reports

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.

List Reports Under a Business Unit

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.

Get Report Schedules for a Report

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

Download Reports

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.

EntAtlasReport

EntAtlasReportRun

EntAtlasReportSchedule

Reference

Time Period Enum

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

Date Range

Metric Scope

Filters

Visit Configuration Values

Attribution Windows

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.

Source Channels