Instagram Ads data source

Learn how to set up an Instagram Ads data source and then move your data to one of the data destinations supported by Coupler.io.

Two steps to complete the setup

Set up your data source
Set up your data destination

1. Set up your data source

1.1. Select an application: Instagram Ads

1.2. Connect an Instagram (Facebook) account

Click "Connect".
Log in to your Facebook account and authorize Coupler.io to import the data on your behalf.

Coupler.io will need access to your Ads & related stats and your email address. Select "Yes" for both options and click "Done".

Review the success message about connection setup and click "Ok".

1.3. Select Data Entity

Select a data category to import: Ad Accounts, Campaigns, Ad sets, Ads, or Insights.

1.4. Select Instagram Ad Account

Specify one or several Ad accounts from which you want to extract data.

Note: “Ad accounts” data entity doesn’t require this field so it’s not available.

The insights data entity has a number of additional settings available under the Advanced settings tab. See below for details.

2. Set up your data destination

Continue the integration setup depending on the destination you want to import data to. Select your tool from the list of supported data destinations and follow the relevant setup guide.

Additional source settings for Insights data entity

When importing Insights, the Advanced settings field appears where you can further customize your import.

Group data by

Select how you want to see your statistics: view ad account totals or get them split by each campaign, ad set, or ad.

From / To dates

Choose the start and end date for your analytics period. You can either insert a particular date in the YYYY-MM-DD format (e.g. 2022-01-20) or a macro (e.g. {{yesterday}}). Learn more about macros.

Split data by periods

You can break down the data into specific periods of time - e.g. monthly, bi-weekly, weekly, daily, etc.

You can use some of the following values:

totals for the period between a start and end date - leave the field empty
daily statistics - use 1
weekly statistics - use 7
monthly statistics - use monthly

To split data in N days periods - use N (e.g. use 10 to break down data into days 1-10, 11-20, 21-30, etc). You can insert any value between 1 and 90. Only integers are allowed.

Columns

You can also adjust the list of columns to be imported. By default, the following are pre-selected:

Ad name
Ad id
Ad set name
Ad set id
Campaign name
Campaign id
Updated time
Reach
Impressions
Quality ranking
Engagement rate ranking
Conversion rate ranking
Amount spend
Conversions: Link clicks

When you click on an empty space in the Columns field, a dropdown list will appear. From here you will be able to add more columns or remove some. The already added fields are highlighted with a light-blue background color.

Breakdowns

You can also use the Columns field to further break down Insights data - e.g. by age, gender, etc. Add or remove them the same way as you did with the columns above.

Coupler.io supports the following breakdowns:

Age
Gender
Country
Region
Device platform
DMA
Hourly stats aggregated by advertiser time zone
Hourly stats aggregated by audience time zone
Impression device
Product id
Publisher platform
Frequency value

Breakdown usage limitations

Off-Facebook action metrics (e.g. Conversions: Registrations Completed) will behave differently when breakdowns are used:

They will return ‘0’ for all breakdown values (e.g. for all countries in a report), or
They will return the correct metric value (e.g. 123 registrations) but the respective breakdown values (e.g. country names) will be returned as “unknown” or “uncategorized”.

Not all breakdowns can be selected together - here are the allowed combinations:

Age and Gender
Country and Region
Impression device and Publisher platform

For more about breakdowns and their limitations you can read the Insights API breakdowns documentation.

Filters

You can filter the data to be imported using Graph API syntax - [filter_1, filter_2, ... , filter_N].

For single filtering you can use a single filter ([filter_1]) - the structure, in this case, is as follows:

[
   {
      "field":"adset.name",
      "operator":"CONTAIN",
      "value":"Blog"
   }
]

field - means the field name that you want to apply the filter to
operator - a condition that you want to use in the filter. Facebook Ads API allows using of one of the following values: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ENDS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE, TOP
value - value to compare a field against: it can be a number (without quotes), a string (with quotes), or an array of values (numbers or strings)

A single filter looks like this:

Some popular examples of a single filter (ready to copy-paste):

Filter by Ad name containing some value:

[
   {
      "field":"ad.name",
      "operator":"CONTAIN",
      "value":"Blog"
   }
]

Filter by Ad set name equal to value:

[
   {
      "field":"adset.name",
      "operator":"EQUAL",
      "value":"Blog"
   }
]

Filter by Amount Spend:

[
   {
      "field":"spend",
      "operator":"GREATER_THAN",
      "value":10.0
   }
]

Filter for either item on a list of actions (for example, action_type must be link_click orlanding_page_view):

[
   {
      "field":"action_type",
      "operator":"IN",
      "value":[
         "link_click",
         "landing_page_view"
      ]
   }
]

Several filters usage in a single importer: [filter_1, filter_2]

[
   {
      "field":"action_type",
      "operator":"IN",
      "value":[
         "link_click",
         "landing_page_view"
      ]
   },
   {
      "field":"adset.name",
      "operator":"CONTAIN",
      "value":"Blog"
   }
]