Insights

Pull live daily Instagram ad metrics for campaigns, ad sets or ads, split by age, gender, country or placement, with paging for long date ranges.

GET /ads/instagram/insights

cURL

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"

200: Success

{
  "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
}

Get live Instagram 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.

• Numbers are read from Meta when you call, not from a nightly copy.

• Use History for the spend we bill. Use Insights for reporting and analysis.

• All money values are in the ad account’s currency, returned in currency on each row.

• 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.

• 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.

​

Header Parameters

​

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.

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

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.

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

cURL

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"

200: Success

{
  "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
}