> ## 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 Instagram Ad Insights by Campaign or Ad

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

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

<ul className="custom-bullets">
  <li>Numbers are read from Meta when you call, not from a nightly copy.</li>

  <li>
    Use [History](/docs/apis/ads/instagram/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. 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

<HeaderAPI />

## Query Parameters

<ParamField query="level" type="string" required>
  What each row reports on: `campaign` or `ad`.

  `adSet` is not supported yet and returns code `101`.
</ParamField>

<ParamField query="ids" type="string">
  Comma-separated campaign or ad ids, up to 50. Required for `level=campaign`.

  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.
</ParamField>

<ParamField query="accountId" type="string">
  The ad account id, with or without the `act_` prefix (`1234567890` or `act_1234567890`).

  Required with `level=ad` when `ids` is left out.
</ParamField>

<ParamField query="metrics" type="string">
  Comma-separated metrics to return. Leave it out to get them all. See [Metrics](#metrics).
</ParamField>

<ParamField query="breakdowns" type="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`.
</ParamField>

<ParamField query="startDate" type="string" default="30 days ago">
  First day, as `YYYY-MM-DD`. It can be up to 37 months ago.
</ParamField>

<ParamField query="endDate" type="string" default="today">
  Last day, as `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  The `nextCursor` from the previous response, to get the next page.
</ParamField>

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

Instagram 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.
</Note>

## 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, `level=adSet` is sent, `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 or ad isn't yours, or `accountId` isn't the ad account Ayrshare has on record for the ids you sent. 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 |

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET "https://api.ayrshare.com/api/ads/instagram/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/instagram/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/instagram/insights', headers=headers, params=params)

  print(r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "platform": "instagram",
    "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": "instagram",
    "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."
  }
  ```
</ResponseExample>


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