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

# 洞察

> 按活动或广告获取实时的每日 Facebook 广告洞察

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} />

获取您的活动或广告的实时 Facebook 广告表现数据，每天一行。
选择所需的指标，按年龄、性别、国家/地区或版位进行细分，并对较长的日期范围进行分页获取。

<ul className="custom-bullets">
  <li>数据在您调用时从 Meta 实时读取，而不是来自每晚生成的副本。</li>

  <li>
    如需查看我们计费的支出，请使用 [历史记录](/docs/apis/ads/facebook/get-ad-history)。如需报告和分析，请使用洞察。
  </li>

  <li>所有货币金额均以广告账户的货币表示，并在每一行的 `currency` 中返回。</li>

  <li>
    活动必须是通过 Ayrshare 为此 Profile 创建的。通过 Ayrshare 为其他 Profile 创建的广告会被拒绝。其他广告 ID
    会使用此 Profile 关联的 Meta 账户读取，因此 Meta 只会返回该账户可以查看的广告。
  </li>

  <li>
    一个请求只涵盖一个广告账户。来自多个广告账户的 ID 会返回错误码 `101`，多个 Ayrshare 没有记录的广告 ID
    也会返回该错误码。请逐个请求这些 ID。
  </li>
</ul>

## 请求头参数

<HeaderAPI />

## 查询参数

<ParamField query="level" type="string" required>
  每一行报告的对象：`campaign` 或 `ad`。

  `adSet` 目前尚不支持，会返回错误码 `101`。
</ParamField>

<ParamField query="ids" type="string">
  以逗号分隔的活动或广告 ID，最多 50 个。`level=campaign` 时必填。

  当 `level=ad` 时，您可以省略 `ids`，改为发送 `accountId`。这会报告您通过 Ayrshare 为此 Profile
  在该广告账户中创建的广告，而不是其中的所有广告。最多支持 50 条此类广告。如果更多，请发送它们的 ID，或按活动进行报告。
  如果未找到任何广告，报告将为空。
</ParamField>

<ParamField query="accountId" type="string">
  广告账户 ID，可带或不带 `act_` 前缀（`1234567890` 或 `act_1234567890`）。

  当 `level=ad` 且省略 `ids` 时必填。
</ParamField>

<ParamField query="metrics" type="string">
  以逗号分隔的要返回的指标。省略时返回全部指标。请参阅 [指标](#metrics)。
</ParamField>

<ParamField query="breakdowns" type="string">
  以逗号分隔的细分维度：`age`、`gender`、`country`、`placement`。此时每一天会为每个值各返回一行，使用
  `age,gender` 时则为每个组合各返回一行。每次请发送一个细分维度，或发送 `age,gender`；Meta
  会拒绝其他组合（例如 `age,country`），因此它们会返回错误码 `101`。
</ParamField>

<ParamField query="startDate" type="string" default="30 天前">
  第一天，格式为 `YYYY-MM-DD`。最早可以是 37 个月前。
</ParamField>

<ParamField query="endDate" type="string" default="今天">
  最后一天，格式为 `YYYY-MM-DD`。
</ParamField>

<ParamField query="cursor" type="string">
  上一个响应中的 `nextCursor`，用于获取下一页。
</ParamField>

<h2 id="metrics">
  指标
</h2>

| 指标 | 类型 | 含义 |
| - | - | - |
| `spend` | number | 支出金额 |
| `impressions` | number | 广告展示次数 |
| `reach` | number | 至少看过一次广告的人数 |
| `clicks` | number | 点击次数 |
| `cpm` | number 或 `null` | 每千次展示费用 |
| `cpc` | number 或 `null` | 每次点击费用。没有点击的日期为 `null` |
| `ctr` | number 或 `null` | 点击率，以百分比表示 |
| `actions` | array | Meta 统计的每种操作类型及其次数 |
| `conversionValue` | number | 购买总价值 |

Facebook 会报告此表中的所有指标。有一个例外：对于带有 `breakdowns` 且开始日期早于 13 个月前的报告，Meta
不会报告 `reach`，因此这些行中会省略 `reach`。对于不报告某个指标的社交网络，该指标会从行中省略，而不是返回 `0`，
请求该指标会返回错误码 `101`。

<Note>
  Meta 会将某些操作计入多种类型，因此请不要将 `actions` 的值相加。例如，`omni_purchase` 已包含
  `purchase`。`conversionValue` 对每笔购买只计算一次。
</Note>

## 分页

每个响应最多返回 500 行。如果还有更多数据，则会设置 `nextCursor`。再次发送相同的请求，并将 `cursor`
设为该值，即可获取下一页。在最后一页，`nextCursor` 为 `null`。

## 错误

| 错误码 | 发生情况 |
| - | - |
| `101` | 缺少参数或参数错误、不支持某个细分维度或指标、发送了 `level=adSet`、`startDate` 早于 37 个月前、发送了超过 50 个 ID、ID 属于多个广告账户，或 Meta 拒绝了该细分维度组合 |
| `400` | 某个活动或广告不属于您，或 `accountId` 不是 Ayrshare 为您发送的 ID 所记录的广告账户。对于没有 Ayrshare 记录的广告，不会检查 `accountId`，该广告会被单独读取 |
| `370` | Meta 无法返回洞察数据。请重试 |

<RequestExample>
  ```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())
  ```
</RequestExample>

<ResponseExample>
  ```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."
  }
  ```
</ResponseExample>


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