Attribution API

The Attribution API allows you 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.

Requirements

Get Lines of Business

Query the business_units to get the lines of business. Send a GET request to the /{business-id} endpoint with the business_units field.

Sample Request

Formatted for readability.

curl GET "https://graph.facebook.com/{business-id}
  ?fields=name,business_units{id,name,ad_platforms}
  &access_token={access-token}"

Sample Response

Formatted for readability.

{
  "name": "The Business",
  "business_units": {
    "data": [
      {
        "id": "{business-unit-1-id}",
        "name": "The Business - Line 1",
        "ad_platforms": {
          "data": [
            {
              "name": "Facebook Ads Platform",
              "id": "11157252756406"
            }
          ]
        },
        "id": "{business-unit-2-id}",
        "name": "The Business - Line 2",
        "ad_platforms": {
          "data": [
            {
              "name": "Facebook Ads Platform",
              "id": "11157252756406"
            }
          ]
        }
      }
    ],
    "paging": {
      "cursors": {
        "before": "QVFIUm...",
        "after": "QVFIUm..."
    }
  },
  "id": "{business-id}"
}

Get Information about a Single Business Unit

Using to the previous Sample Request, add ad_platforms fields to the GET request.

Sample Request

Formatted for readability.

curl GET "https://graph.facebook.com/{business-id}
  ?fields=name,business_units{
    id,
    name,
    ad_platforms{
      id,
      name,
      live_status,
      platform_type,
      step_progress,
      last_modified_by,
      connection_type,
      created_date,
      custom_tags
    }
  }
&access_token={access-token}"

Sample Response

Formatted for readability.

{
  "name": "Business 1",
  "business_units": {
    "data": [
      {
        "id": "{business-unit-id-1"},
        "name": "Line of Business 1",
        "ad_platforms": {
          "data": [
            {
              "name": "Facebook Ads Platform",
              "id": "11157252756406",
              "live_status": "awaiting_traffic",
              "platform_type": "publisher",
              "setup_progress": "complete",
              "last_modified_by": {
                "id": "{user-id}",
                "name": "User Name"
              },
              "connection_type": "facebook",
              "created_date": "2019-01-15T00:43:06+0000",
              "custom_tags": {
                "data": [
                  {
                    "click_tag": "}",
                    "view_tag": ";"
                  }
                ]
              },
            },
          ]
        }
      }
    ],
      {
        "id": "{business-unit-id-2"},
        "name": "Line of Business 2"
        "ad_platforms": {
          "data": [
            {
              "name": "Facebook Ads Platform",
              "id": "11157252756406",
    ...    //formatted for brevity

For a complete list of business_units fields, visit our Graph API Reference

Diagnostics

Send a GET request to the /{business-unit}/diagnostic endpoint to find potential issues.

Sample Request

Formatted for readability.

curl GET "https://graph.facebook.com/{business-unit-id}
    ?fields=diagnostics{id,last_action_time,last_fired_time,type,status}
    &access_token={access-token}"

Sample Response

{
  "{business-unit-id}": {
    "diagnostics": {
      "data": [
        {
          "id": "{diagnostic-id-1}",
          "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-2}",
          "last_fired_time": "2019-06-18T03:01:15+0000",
          "type": "unassigned_ad_account",
          "status": "resolved"
        }
      ]
    },
  }
}

Visit the Business Unit Diagnostic Reference for a list of fields and values.

Metrics

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

Visit the Business Unit Campaigns Reference for a list of metric scope values.

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 standard and custom conversion events such as app installs, purchases, app.

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.

ParameterDescription

time_period

Time Period

The time period for which we want the conversion paths, for example: last_thirty_days

click_lookback_window

Attribution Windows

The number of seconds to look back for clicks, attribution window

view_lookback_window

Attribution Windows

The number of seconds to look back for impressions, attribution window

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:

NameValueNote

Unknown

0

Unable to determine the type of contributing device(s)

DesktopOnly

1

MobileOnly

2

DesktopAndMobile

3

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:

NameValueNote

Unknown

0

Unable to determine the device type a conversion occurred on

Desktop

1

Mobile

2

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.

Note: The default value of the attribution windows is 7d_click. Set the action_attribution_windows field to customize the attribution window values.

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
Metric NameMetric Suffix

Conversions

_convs

Conversions per 1,000 Impressions

_convs_per_1k_impress

Click Conversion Rate

_convs_per_click

Visit Conversion Rate

_convs_per_visit

Cost per Conversion

Value returned in 1/100,000,000 of the business unit's currency

_cpa

Conversion Value

_revenue

Return on Ad Spend

_roas

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 NameMetric

Cost per 1,000 Impressions

Value returned in 1/100,000,000 of the business unit's currency

cost_per_1k_impressions

Cost per Click

Value returned in 1/100,000,000 of the business unit's currency

cost_per_click

Cost per Visit

Value returned in 1/100,000,000 of the business unit's currency

cost_per_visit

Conversions

Based on attribution model

[attribution_model]_convs

Conversions per 1,000 Impressions

Based on attribution model

[attribution_model]_convs_per_1k_impress

Click Conversion Rate

Based on attribution model

[attribution_model]_convs_per_click

Cost Per Conversion

Based on attribution model, value returned in 1/100,000,000 of the business unit's currency

[attribution_model]_cpa

Conversion Value

Based on attribution model

[attribution_model]_revenue

Return on Ad Spend

Based on attribution model

[attribution_model]_roas

Cost

Value returned in 1/100,000,000 of the business unit's currency

net_media_cost

Click-Through Rate, or CTR

report_click_through_rate

Clicks

report_clicks

Impressions

report_impressions

Visits

report_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.

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_schedules

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


FieldDescription

id

ID of the report.

compression_type

Compression type of the report file.

created_date

Date when report was created.

created_date

Date when report was created.

deprecation_reasons

If the report includes deprecated features, this includes all reasons that it is deprecated.

file_format

Report file format.

last_modified_date

Date when the report was last edited.

last_report_run

Last report run for this report.

report_runs

List of report runs for the report.

report_schedules

List of report schedules for the report.

name

Name of the report.

EntAtlasReportRun


FieldDescription

id

ID of the report run.

completed_date

Date when the report run was completed.

compression_type

Compression type of report file.

created_date

Date when report run was created.

data

Link to download the report run. Requires the query parameter “filename”.

deprecation_reasons

If the report run includes deprecated features, this includes all reasons that it is deprecated.

error_code

Numeric code representing error.

file_format

Report file format.

last_modified_date

Date on which the report was last edited.

name

Name of the report run.

report

Report associated with the report run.

schedule

Report schedule associated with the report run.

status

Current status of the report run.

version

Version number of the report.

EntAtlasReportSchedule


FieldDescription

id

ID of the report schedule.

created_date

Date when the report schedule was created.

date_range

Start and end date for the report schedule to run.

is_active

Specifies if the report schedule is active.

last_modified_date

Date on which the report schedule was last edited.

recurrence_type

Type for the frequency at which an event is scheduled to occur.

report

Report associated with the report schedule.

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

PropertyDescription

begin_date

int

The begin date of the desired date range in Unix time.

end_date

int

The end date of the desired date range in Unix time.

time_zone

string

The name of the time zone being queried over.

Example: America/New_York

type

The value is required to be 'ABSOLUTE'

Metric Scope

Filters

PropertyDescription

click_lookback_window

string

String representation of the click window from the desired attribution window

view_lookback_window

string

String representation of the impression window from the desired attribution window

visit_configuration

Visit Configuration

Allows adjustment of how visits are considered when calculating attribution.

Visit Configuration Values

PropertyDescription

include_all

Credit all visits normally.

include_all_prefer_paid

Credit direct visits and prefer paid touchpoints over organic touchpoints.

include_paid_organic_prefer_paid

Do not credit direct visits and prefer paid touchpoints over organic touchpoints.

include_paid_organic

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.

exclude_all

Do not credit visits.

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.

values for queries that do not set action_attribution_windows when pulling results we will use 7d_click.

Attribution WindowClick Window ValueView 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

Source Channels

NameEnum NameEnum Value

Direct

DIRECT

0

Organic

ORGANIC

1

Paid Facebook

PAID_FB

2

Paid Third Party

PAID_THIRD_PARTY

3

Paid

Combination of Paid Facebook and Paid Third Party

PAID_ALL

4