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:

ValueDescription

ads_linking_to_app_store

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.

ads_linking_to_url_shortener

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.

generic_clicks_to_visits_drop

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.

missing_landing_page_pixel

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.

unassigned_ad_account

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.

unassigned_landing_page_pixel

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.

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.

MetricMetric Name in UI

cost_per_1k_impressions

Cost per 1,000 Impressions

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

cost_per_click

Cost per Click

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

cost_per_visit

Cost per Visit

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

net_media_cost

Cost

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

report_click_through_rate

Click-Through Rate, or CTR

report_clicks

Clicks

report_impressions

Impressions

report_visits

Visits

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:

PropertyDescription

date_range

Date Range

The exact date range to query over. This property is only required if the value provided for time_period is DATE_RANGE. If any other values are passed in for time_period, this property is ignored.

filters

Metric Scope Filters

Filters that can be used to narrow the results based on attribution window or visit configuration

should_include_prior_period

boolean

Default value: false


Determines if the prior time periods data should also be included in the query.


For example, if your time period is LAST_THIRTY_DAYS, the 30 days prior to that period will also be included in the results. If you want to see the exact dates the prior period includes, add the .summary(1) parameter to your request.

time_period

Time Period

Default value: ALL_DATES


Determines the dates that the query is run for.

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.

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.

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_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


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.

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