> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/instagram-ads.md).

# Instagram Ads

Export Instagram Ads campaigns, ad sets, and performance insights to Google Sheets, BigQuery, or 50+ destinations via Coupler.io.

Instagram Ads is Meta's advertising platform for running paid campaigns across Instagram placements — Feed, Stories, Reels, Explore, and more. With Coupler.io, you can automatically export your Instagram Ads data — campaign performance, ad sets, individual ads, and detailed insights — to your destination of choice without writing a single line of code.

## Why connect Instagram Ads to Coupler.io?

* **Centralize your ad reporting** — pull campaigns, ad sets, ads, and insights into one place alongside data from other channels
* **Flexible breakdowns** — slice performance by age, gender, country, placement, device, and dozens of other dimensions
* **Multi-account support** — connect multiple ad accounts and use the Append transformation to combine them into a single report
* **Send data anywhere** — export to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like ChatGPT, Claude, or Gemini for analysis and automated insights

## Prerequisites

* A Facebook account with admin or advertiser access to at least one Instagram Ad account
* Your Instagram account must be connected to a Facebook Business Manager
* You cannot import data from public Instagram profiles — only from ad accounts you manage

## Quick start

{% hint style="success" %}
If you want campaign performance data with breakdowns (age, gender, placement, etc.), start with the **Reports and Insights** entity. For a structural overview of what's in your account, grab Campaigns, Ad Sets, or Ads first.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow and select Instagram Ads as your source.** In Coupler.io, click **Add data flow**, then search for and select **Instagram Ads**.
{% endstep %}

{% step %}
**Authenticate with Facebook.** Click **Connect** and sign in with the Facebook account that has access to your Instagram ad accounts. Grant the requested permissions — Coupler.io needs these to read your ad data.
{% endstep %}

{% step %}
**Select your ad account and entity.** Choose the ad account(s) you want to pull data from. Then pick an entity: Reports and Insights, List of Campaigns, List of Ad Sets, or List of Ads.
{% endstep %}

{% step %}
**Choose your destination.** Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Claude.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Instagram Ads data will appear in your destination.
{% endstep %}
{% endstepper %}

## Instagram Ads data overview

The Instagram Ads source gives you access to four entities: performance insights with granular breakdowns, and structural lists of your campaigns, ad sets, and ads. The most powerful entity is **Reports and Insights**, which lets you combine metrics and dimensions in a highly flexible way.

## Available entities

| Entity               | Best used for                                            |
| -------------------- | -------------------------------------------------------- |
| Reports and Insights | Performance analysis, trend tracking, audience reporting |
| List of Campaigns    | Campaign inventory, status monitoring, budget review     |
| List of Ad Sets      | Targeting and scheduling overview                        |
| List of Ads          | Creative-level tracking, ad status monitoring            |

## Reports and Insights metrics

#### Default metrics

| Metric                 | Description                           |
| ---------------------- | ------------------------------------- |
| Amount Spent (`spend`) | Total ad spend for the period         |
| Impressions            | Number of times your ads were shown   |
| Reach                  | Unique accounts that saw your ads     |
| Frequency              | Average times each person saw your ad |
| Clicks                 | Total clicks on your ads              |
| CPC                    | Cost per click                        |
| CPM                    | Cost per 1,000 impressions            |
| CTR                    | Click-through rate                    |

#### Additional metrics (selectable)

| Metric              | Description                                             |
| ------------------- | ------------------------------------------------------- |
| Conversions         | Actions completed as a result of your ad                |
| Cost per conversion | Spend divided by conversions                            |
| Video views         | Number of times video was played                        |
| Video play rate     | Percentage of impressions that resulted in a video play |
| Engagement rate     | Interactions relative to impressions                    |
| Link clicks         | Clicks specifically on your ad's link                   |
| Outbound clicks     | Clicks that take users off-platform                     |
| Post reactions      | Likes, loves, and other reactions                       |
| Post comments       | Comments left on your ads                               |
| Post shares         | Times your ad was shared                                |

## Breakdowns (dimensions)

Breakdowns let you split your insights data by a wide range of attributes. You can select one breakdown group per report.

#### Frequently used breakdowns

| Breakdown                             | Use case                                            |
| ------------------------------------- | --------------------------------------------------- |
| Age, Gender                           | Audience demographic analysis                       |
| Country, Region                       | Geographic performance                              |
| Publisher platform                    | Compare Instagram vs. Facebook vs. Audience Network |
| Publisher platform, Platform position | Feed vs. Stories vs. Reels vs. Explore              |
| Impression device                     | Mobile vs. desktop performance                      |
| DMA (Designated Market Area)          | US regional targeting analysis                      |

#### Action and conversion breakdowns

| Breakdown              | Use case                              |
| ---------------------- | ------------------------------------- |
| Action type            | See what types of actions users took  |
| Action device          | Which device drove the conversion     |
| Action destination     | Where users landed after clicking     |
| Conversion destination | Final destination of converting users |

#### Asset-level breakdowns

| Breakdown                      | Use case                                |
| ------------------------------ | --------------------------------------- |
| Action carousel card ID / name | Performance by individual carousel card |
| Image asset                    | Compare images in dynamic creative      |
| Video asset                    | Video-level performance                 |
| Title asset, Body asset        | Copy performance in dynamic ads         |
| Ad format asset                | Format-level breakdown                  |

## Date range and aggregation options

* Set a **start date** and **end date** using the date pickers to define your reporting window
* **Split data by period**: Daily, Weekly, Monthly, or Totals only
* **Attribution settings**: inherit from ad account, ad set, or set manually (1-day click, 7-day click, 28-day click, 1-day view, 7-day view, and more)

## Common metric combinations

* **Audience report**: Spend + Impressions + Reach + CPC, broken down by Age + Gender
* **Placement report**: Spend + CTR + CPC, broken down by Publisher platform + Platform position
* **Geographic report**: Spend + Conversions + Cost per conversion, broken down by Country
* **Creative report**: Impressions + CTR + Engagement rate, broken down by Image asset or Video asset

## Use cases by role

{% tabs %}
{% tab title="Marketers" %}

* Track daily spend vs. performance across campaigns and ad sets
* Compare Instagram placements (Feed, Stories, Reels) to see where your budget performs best
* Build audience demographic reports by age and gender to validate targeting assumptions
* Use Append in Coupler.io to combine Instagram Ads data with Facebook Ads or TikTok Ads for a full cross-channel view
* Send insights to ChatGPT or Claude to generate performance summaries and optimization suggestions automatically
  {% endtab %}

{% tab title="Finance teams" %}

* Export monthly spend totals per ad account for budget reconciliation
* Use the "Totals only" aggregation and a monthly split to produce clean spend reports
* Join campaign-level data with CRM or revenue data in BigQuery to calculate true ROAS
* Track frequency to flag campaigns that may be over-serving and burning budget inefficiently
  {% endtab %}

{% tab title="Analysts" %}

* Use multiple breakdowns (e.g., Country + Action type) to build attribution models
* Pull List of Campaigns and List of Ad Sets alongside Insights and use the Join transformation to enrich performance data with campaign metadata
* Use the Publisher platform breakdown to separate Instagram-specific performance from broader Meta placements
* Export to Looker Studio or BigQuery for long-term trend analysis across date ranges
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Instagram Ads data is served through the **Meta (Facebook) Graph API** — so you connect via Facebook OAuth, not an Instagram login
* You can only pull data from **ad accounts you manage** — public profile data and organic post insights are not available through this source
* Some metrics are not available for all ad objectives — for example, video metrics only appear when your campaign includes video creatives
* Deprecated metrics (such as older profile performance fields) may return empty or cause errors — check Meta's current API docs if a metric stops returning data
* Filters use **Graph API syntax** — refer to the Coupler.io Help Center article for correct filter formatting
* The **Publisher platform** breakdown will show data across Instagram, Facebook, and Audience Network if your campaigns run on multiple placements — use filters or the breakdown to isolate Instagram-only performance

## Instagram Ads common issues

### Connection issues

<details>

<summary>I can't connect my Instagram account — I only see Facebook login</summary>

This is expected. Instagram Ads uses the Meta (Facebook) Graph API, so you must authenticate with the **Facebook account** that is linked to your Instagram Business account and has access to your ad accounts. Make sure your Instagram account is connected to a Facebook Business Manager before attempting to connect.

</details>

<details>

<summary>My ad account doesn't appear in the account selector</summary>

This usually means the Facebook account you authenticated with doesn't have the right role on that ad account. You need **admin or advertiser access** in Meta Business Manager. Ask the account owner to grant you access, then reconnect in Coupler.io.

</details>

<details>

<summary>I'm trying to import public Instagram profile data but get an error</summary>

Coupler.io's Instagram Ads source only works with **paid ad account data** — it does not support public profile data or organic post insights. If you need organic Instagram metrics, that requires a separate Instagram Business/Creator account connection, which is a different data source.

</details>

### Missing data

<details>

<summary>Some metrics are empty or returning no data</summary>

This typically happens because a metric isn't compatible with your campaign objective or ad format. For example, video metrics only appear when your ads include video. Some older metrics were also deprecated by Meta — if a field used to work and now returns nothing, check whether Meta has retired it from the API.

</details>

<details>

<summary>My Insights report shows no data for a specific date range</summary>

Check that your ad campaigns were actually running during the selected period. Also confirm that the **start date** and **end date** are set correctly using the date pickers — an inverted date range (end before start) will return nothing. If campaigns ran but data is still missing, try narrowing the date range to isolate the issue.

</details>

<details>

<summary>Monthly stats aren't showing correctly</summary>

If you're expecting monthly-aggregated data, make sure you've set **Split data by period** to **Monthly** in the report settings. By default, the report uses a daily breakdown, which can look misleading if you're expecting one row per month. Also ensure your date range spans at least one full calendar month.

</details>

### Permission errors

<details>

<summary>I get a permissions error when running the data flow</summary>

This usually means the Facebook account used to connect doesn't have sufficient access to the ad account, or that the required API permissions were not granted during OAuth. Try reconnecting the source in Coupler.io and make sure you accept **all** permission requests during the Facebook login flow. If the issue persists, verify your role in Meta Business Manager.

</details>

### Data discrepancies

<details>

<summary>The numbers in Coupler.io don't match what I see in Meta Ads Manager</summary>

A few things can cause this:

* **Attribution windows**: If your Coupler.io report uses a different attribution window than what's set as default in Meta Ads Manager, numbers will differ. Align attribution settings between both.
* **Time zone**: Meta reports metrics based on the ad account's time zone. If your date range crosses midnight in a different time zone, day-level totals may not match.
* **Data delays**: Meta's API can have a delay of up to 48–72 hours for finalized conversion data. Very recent data may still be in flux.

</details>

### Rate limits

<details>

<summary>My data flow fails with a rate limit error</summary>

Meta's Graph API enforces rate limits per ad account. If you're pulling large date ranges, many breakdowns, or running multiple data flows against the same account simultaneously, you may hit these limits. Try reducing the date range, simplifying breakdowns, or spacing out your data flow runs.

</details>

## Instagram Ads FAQ

<details>

<summary>Do I need an Instagram login to connect?</summary>

No. Instagram Ads connects through the **Meta (Facebook) Graph API**, so you authenticate with your Facebook account — not your Instagram credentials. The Facebook account must have admin or advertiser access to the ad account linked to your Instagram Business profile.

</details>

<details>

<summary>Can I pull organic Instagram data — like post reach, profile visits, or follower counts?</summary>

No, this source is for **Instagram Ads (paid) data only**. Organic metrics like post insights, profile visits, or story views are not available through the Instagram Ads source. You would need a separate Instagram Business account integration for those.

</details>

<details>

<summary>Why does the Publisher platform breakdown show Facebook and Audience Network data, not just Instagram?</summary>

If your Meta campaigns are set to run across multiple placements, the Publisher platform breakdown will include all platforms where your ads ran — Instagram, Facebook, Audience Network, and Messenger. To isolate Instagram-only performance, use the Graph API filter to restrict results to `publisher_platform = instagram`, or analyze the breakdown column in your destination tool.

</details>

<details>

<summary>Can I combine Instagram Ads data from multiple ad accounts in one report?</summary>

Yes. Add multiple ad accounts as separate sources within the same data flow and use the **Append** transformation to stack them into one dataset. Make sure to include the `account_name` column so you can tell the accounts apart in your reports.

</details>

<details>

<summary>How do I set up filters for Insights reports?</summary>

Filters for the Insights entity use **Meta's Graph API filter syntax** — they're not a simple dropdown. For example, to filter by campaign ID or effective status, you need to write the filter expression manually. See the [data overview](#instagram-ads-data-overview) for the correct syntax and examples.

</details>

<details>

<summary>Why do my monthly stats look wrong or incomplete?</summary>

This is usually a split period setting issue. By default, Insights reports use a **daily breakdown**. To get monthly-aggregated data, set **Split data by period** to **Monthly** in the report settings, and make sure your date range covers at least one full calendar month.

</details>

<details>

<summary>Can I use Coupler.io to send Instagram Ads data to an AI tool for analysis?</summary>

Yes. Coupler.io supports AI destinations including **ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw**. You can send your Insights data directly to these tools to generate performance summaries, flag anomalies, or get optimization suggestions — no manual copy-pasting required.

</details>

<details>

<summary>Some metrics I used before are no longer returning data — what happened?</summary>

Meta periodically deprecates metrics from its API. If a field that previously worked now returns nothing, it may have been retired. Check Meta's API changelog or the Coupler.io Help Center for known deprecated fields.

</details>

{% hint style="info" %}
For a full breakdown of available metrics, dimensions, and breakdowns, see [Data Overview](#instagram-ads-data-overview). If you're running into connection or permission problems, check [Common Issues](#instagram-ads-common-issues). For tips on structuring your reports efficiently, visit [Best Practices](https://docs.coupler.io/sources/category/ppc/instagram-ads/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/ppc/instagram-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
