> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Insights

> Get Live Daily Facebook Ad Insights by Campaign, Ad Set or Ad

Get live Facebook ad performance, one row per day, for your campaigns, ad sets or ads.
Pick the metrics you want, split them by age, gender, country or placement, and page through long date ranges.

<ul>
  <li>Numbers are read from Meta when you call, not from a nightly copy.</li>

  <li>
    Use [History](/docs/apis/ads/facebook/get-ad-history) for the spend we bill. Use Insights for reporting
    and analysis.
  </li>

  <li>All money values are in the ad account's currency, returned in `currency` on each row.</li>

  <li>
    Campaigns must have been created through Ayrshare for this profile, and ad sets must be in such
    a campaign. An ad created through
    Ayrshare for another profile is refused. Other ad ids are read with this profile's linked Meta
    account, so Meta only returns ads that account can see.
  </li>

  <li>
    One request covers one ad account. Ids from several ad accounts return code `101`, and so do
    several ad ids that Ayrshare has no record of. Ask for those one at a time.
  </li>
</ul>

## Header Parameters

**Authorization** `string` *required*

[API Key](/docs/apis/overview#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](/docs/apis/overview#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## Query Parameters

**level** `string` *required*

What each row reports on: `campaign`, `adSet` or `ad`.

**ids** `string`

Comma-separated campaign, ad set or ad ids, up to 50. Required for `level=campaign` and
`level=adSet`.

With `level=ad`, you can leave `ids` out and send `accountId` instead. This reports on the ads
you created through Ayrshare for this profile in that ad account, not on every ad in it. It works
for up to 50 such ads. For more, send their ids, or report by campaign. If none are found, the
report is empty.

**accountId** `string`

The ad account id, with or without the `act_` prefix (`1234567890` or `act_1234567890`).

Required with `level=ad` when `ids` is left out.

**metrics** `string`

Comma-separated metrics to return. Leave it out to get them all. See [Metrics](#metrics).

**breakdowns** `string`

Comma-separated breakdowns: `age`, `gender`, `country`, `placement`. Each day then has one row per
value, or per combination with `age,gender`. Send one breakdown at a time, or `age,gender`; Meta
refuses other mixes (such as `age,country`), so they return code `101`.

**startDate** `string` (default: 30 days ago)

First day, as `YYYY-MM-DD`. It can be up to 37 months ago.

**endDate** `string` (default: today)

Last day, as `YYYY-MM-DD`.

**cursor** `string`

The `nextCursor` from the previous response, to get the next page.

## Metrics

| Metric | Type | Meaning |
| - | - | - |
| `spend` | number | Amount spent |
| `impressions` | number | Times the ad was shown |
| `reach` | number | People who saw the ad at least once |
| `clicks` | number | Clicks |
| `cpm` | number or `null` | Cost per 1,000 impressions |
| `cpc` | number or `null` | Cost per click. `null` on a day with no clicks |
| `ctr` | number or `null` | Click-through rate, in percent |
| `actions` | array | Each action type Meta counted, with its count |
| `conversionValue` | number | Total value of purchases |

Facebook reports every metric in this table. One exception: Meta does not report `reach` for a report with
`breakdowns` that starts more than 13 months ago, so `reach` is left out of those rows. On networks that don't report a metric, it is left out
of the rows rather than returned as `0`, and asking for it returns code `101`.

> [!NOTE]
>
> Meta counts some actions under more than one type, so don't add `actions` values together. For
> example, `omni_purchase` already includes `purchase`. `conversionValue` counts each purchase once.

## Paging

Each response returns up to 500 rows. If there are more, `nextCursor` is set. Send the same request
again with `cursor` set to that value to get the next page. On the last page, `nextCursor` is `null`.

## Errors

| Code | When |
| - | - |
| `101` | A parameter is missing or wrong, a breakdown or metric isn't supported, `startDate` is more than 37 months ago, more than 50 ids are sent, the ids are in more than one ad account, or Meta refuses the breakdown combination |
| `400` | A campaign, ad set or ad isn't yours, or `accountId` isn't the ad account Ayrshare has on record for the ids you sent. For an ad set, `accountId` must also be the ad account Meta reports for it. For an ad with no Ayrshare record, `accountId` is not checked and the ad is read on its own |
| `370` | Meta could not return the insights. Try again |

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";
const params = new URLSearchParams({
  level: "campaign",
  ids: "120200000000000001",
  startDate: "2026-09-01",
  endDate: "2026-09-02",
});

fetch(`https://api.ayrshare.com/api/ads/facebook/insights?${params}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${API_KEY}` },
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {'Authorization': 'Bearer API_KEY'}
params = {
    'level': 'campaign',
    'ids': '120200000000000001',
    'startDate': '2026-09-01',
    'endDate': '2026-09-02',
}

r = requests.get('https://api.ayrshare.com/api/ads/facebook/insights', headers=headers, params=params)

print(r.json())
```

```json 200: Success theme={"system"}
{
  "status": "success",
  "platform": "facebook",
  "level": "campaign",
  "startDate": "2026-09-01",
  "endDate": "2026-09-02",
  "insights": [
    {
      "date": "2026-09-01",
      "level": "campaign",
      "id": "120200000000000001",
      "currency": "USD",
      "spend": 12.34,
      "impressions": 4000,
      "reach": 3100,
      "clicks": 80,
      "cpm": 3.085,
      "cpc": 0.15425,
      "ctr": 2,
      "actions": [
        { "type": "link_click", "value": 75 },
        { "type": "omni_purchase", "value": 3 }
      ],
      "conversionValue": 89.97
    }
  ],
  "count": 1,
  "nextCursor": null
}
```

```json 200: Breakdowns theme={"system"}
{
  "status": "success",
  "platform": "facebook",
  "level": "ad",
  "startDate": "2026-09-01",
  "endDate": "2026-09-01",
  "insights": [
    {
      "date": "2026-09-01",
      "level": "ad",
      "id": "120210000000000001",
      "age": "25-34",
      "gender": "female",
      "currency": "EUR",
      "spend": 1.5,
      "impressions": 300
    },
    {
      "date": "2026-09-01",
      "level": "ad",
      "id": "120210000000000001",
      "age": "25-34",
      "gender": "male",
      "currency": "EUR",
      "spend": 1,
      "impressions": 200
    }
  ],
  "count": 2,
  "nextCursor": null
}
```

```json 400: Not Yours theme={"system"}
{
  "action": "ads",
  "status": "error",
  "code": 400,
  "message": "The ad is not found or not authorized."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.