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"
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);
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())
{
"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
}
{
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Instagram Ads
洞察
按活动或广告获取实时的每日 Instagram 广告洞察
GET
/
ads
/
instagram
/
insights
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"
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);
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())
{
"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
}
{
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
获取您的活动或广告的实时 Instagram 广告表现数据，每天一行。
选择所需的指标，按年龄、性别、国家/地区或版位进行细分，并对较长的日期范围进行分页获取。
Instagram 会报告此表中的所有指标。有一个例外：对于带有
- 数据在您调用时从 Meta 实时读取，而不是来自每晚生成的副本。
- 如需查看我们计费的支出，请使用 历史记录。如需报告和分析，请使用洞察。
- 所有货币金额均以广告账户的货币表示，并在每一行的
currency中返回。 - 活动必须是通过 Ayrshare 为此 Profile 创建的。通过 Ayrshare 为其他 Profile 创建的广告会被拒绝。其他广告 ID 会使用此 Profile 关联的 Meta 账户读取，因此 Meta 只会返回该账户可以查看的广告。
- 一个请求只涵盖一个广告账户。来自多个广告账户的 ID 会返回错误码
101，多个 Ayrshare 没有记录的广告 ID 也会返回该错误码。请逐个请求这些 ID。
请求头参数
查询参数
string
必填
每一行报告的对象：
campaign 或 ad。adSet 目前尚不支持，会返回错误码 101。string
以逗号分隔的活动或广告 ID，最多 50 个。
level=campaign 时必填。当 level=ad 时，您可以省略 ids，改为发送 accountId。这会报告您通过 Ayrshare 为此 Profile
在该广告账户中创建的广告，而不是其中的所有广告。最多支持 50 条此类广告。如果更多，请发送它们的 ID，或按活动进行报告。
如果未找到任何广告，报告将为空。string
广告账户 ID，可带或不带
act_ 前缀（1234567890 或 act_1234567890）。当 level=ad 且省略 ids 时必填。string
以逗号分隔的细分维度：
age、gender、country、placement。此时每一天会为每个值各返回一行，使用
age,gender 时则为每个组合各返回一行。每次请发送一个细分维度，或发送 age,gender；Meta
会拒绝其他组合（例如 age,country），因此它们会返回错误码 101。string
默认值:"30 天前"
第一天，格式为
YYYY-MM-DD。最早可以是 37 个月前。string
默认值:"今天"
最后一天，格式为
YYYY-MM-DD。string
上一个响应中的
nextCursor，用于获取下一页。指标
| 指标 | 类型 | 含义 |
|---|---|---|
spend | number | 支出金额 |
impressions | number | 广告展示次数 |
reach | number | 至少看过一次广告的人数 |
clicks | number | 点击次数 |
cpm | number 或 null | 每千次展示费用 |
cpc | number 或 null | 每次点击费用。没有点击的日期为 null |
ctr | number 或 null | 点击率，以百分比表示 |
actions | array | Meta 统计的每种操作类型及其次数 |
conversionValue | number | 购买总价值 |
breakdowns 且开始日期早于 13 个月前的报告，Meta
不会报告 reach，因此这些行中会省略 reach。对于不报告某个指标的社交网络，该指标会从行中省略，而不是返回 0，
请求该指标会返回错误码 101。
Meta 会将某些操作计入多种类型，因此请不要将
actions 的值相加。例如，omni_purchase 已包含
purchase。conversionValue 对每笔购买只计算一次。分页
每个响应最多返回 500 行。如果还有更多数据，则会设置nextCursor。再次发送相同的请求，并将 cursor
设为该值，即可获取下一页。在最后一页，nextCursor 为 null。
错误
| 错误码 | 发生情况 |
|---|---|
101 | 缺少参数或参数错误、不支持某个细分维度或指标、发送了 level=adSet、startDate 早于 37 个月前、发送了超过 50 个 ID、ID 属于多个广告账户，或 Meta 拒绝了该细分维度组合 |
400 | 某个活动或广告不属于您，或 accountId 不是 Ayrshare 为您发送的 ID 所记录的广告账户。对于没有 Ayrshare 记录的广告，不会检查 accountId，该广告会被单独读取 |
370 | Meta 无法返回洞察数据。请重试 |
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"
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);
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())
{
"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
}
{
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}