> ## 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="/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="/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="/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 广告的每日广告支出和表现指标详情。
此端点提供全面的广告分析数据，包括按日细分、按目标划分的表现以及聚合指标。

<Tip>
  `dailySpend` 数组包含每条广告的每日历史支出与表现指标。数据截止于美东时间上午 8 点。
  如果需要实时支出数据，或尚未产生支出，请使用 [ads 端点](/apis/ads/facebook/get-boosted-ads)。

  如果没有可用的支出数据或尚未产生支出，则**不会**返回该广告。
</Tip>

<ul className="custom-bullets">
  <li>
    指标是通过 Facebook 的报表 API 计算得出，可能存在轻微延迟（最长 24 小时）。
  </li>

  <li>`byGoalType` 和 `byGoalTitle` 部分按目标（objective）对表现指标进行分组。</li>
  <li>使用 `adId` 或 `postId` 过滤器可将结果限定到特定的活动。</li>
  <li>所有货币金额均以广告账户的货币显示（通常为 USD）。</li>
  <li>`goalPerformance` 部分会突出显示表现最佳的广告目标。</li>
</ul>

<Info>
  此端点仅返回通过 [Boost Post](/apis/ads/facebook/boost-post) 端点创建的 Facebook 广告。
  通过 Facebook 广告管理器或其他第三方工具创建的广告不会被返回。
</Info>

## 请求头参数

<HeaderAPI />

## 查询参数

<ParamField query="accountId" type="number">
  将结果过滤到特定账户 ID。
</ParamField>

<ParamField query="adId" type="string">
  将结果过滤到特定广告 ID。
</ParamField>

<ParamField query="postId" type="string">
  将结果过滤到与特定 [Ayrshare 帖子 ID](/apis/overview#ayrshare-post-id) 相关联的广告。
</ParamField>

<ParamField query="fbPostId" type="string">
  将结果过滤到与特定 [Facebook 社交帖子 ID](/apis/overview#social-post-id) 相关联的广告。
</ParamField>

<ParamField query="limit" type="number" default={25}>
  最多获取 `limit` 条广告。最大值为 500。
</ParamField>

<ParamField query="startDate" type="string" default="30 days ago">
  报告期的开始日期，采用 ISO 8601 格式（默认：30 天前）
</ParamField>

<ParamField query="endDate" type="string" default="today">
  报告期的结束日期，采用 ISO 8601 格式（默认：今天）
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET https://api.ayrshare.com/api/ads/facebook/spend?accountId=1234567890
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";

  fetch("https://api.ayrshare.com/api/ads/facebook/spend?accountId=1234567890", {
        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'}

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

  print(r.json())
  ```

  ```php PHP theme={"system"}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => "https://api.ayrshare.com/api/ads/facebook/spend",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer API_KEY"
      ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
      echo "cURL Error: " . $err;
  } else {
      echo $response;
  }
  ?>
  ```

  ```csharp C# theme={"system"}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

          var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/spend");
          var content = await response.Content.ReadAsStringAsync();

          Console.WriteLine(content);
      }
  }
  ```

  ```go Go theme={"system"}
  package main

  import (
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      client := &http.Client{}
      req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/facebook/spend", nil)

      req.Header.Add("Authorization", "Bearer API_KEY")

      resp, err := client.Do(req)
      if err != nil {
          fmt.Println("Error:", err)
          return
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={"system"}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class GetAdSpend {
      public static void main(String[] args) {
          HttpClient client = HttpClient.newHttpClient();

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://api.ayrshare.com/api/ads/facebook/spend"))
              .header("Authorization", "Bearer API_KEY")
              .GET()
              .build();

          try {
              HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
              System.out.println(response.body());
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  ```

  ```ruby Ruby theme={"system"}
  require 'net/http'
  require 'json'
  require 'uri'

  uri = URI.parse('https://api.ayrshare.com/api/ads/facebook/spend')

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = 'Bearer API_KEY'

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
    http.request(request)
  end

  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success No Param theme={"system"}
  {
      "status": "success",
      "history": [
          {
              "adId": "6683876017501",
              "adName": "API Post 1 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
              "budgetDaily": 4,
              "budgetType": "daily",
              "deliveryStatus": "ACTIVE",
              "goal": {
                  "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
                  "title": "Get More Engagement",
                  "type": "engagement"
              },
              "isActive": true,
              "isComplete": false,
              "metrics": {
                  "clicks": 3,
                  "impressions": 1035,
                  "reach": 1026,
                  "frequency": 0,
                  "ctr": 0,
                  "cpm": 1.53,
                  "cpp": 1.54,
                  "cpc": 0
              },
              "network": "facebook",
              "postId": "DE6gpw8kxlonHy6eb7L1",
              "spend": 1.58,
              "spendDate": "2025-04-02T00:00:00.000Z",
              "status": "ACTIVE"
          },
          {
              "adId": "120218167147110411",
              "adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
              "budgetDaily": 4,
              "budgetType": "daily",
              "deliveryStatus": "ACTIVE",
              "goal": {
                  "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
                  "title": "Get More Engagement",
                  "type": "engagement"
              },
              "isActive": true,
              "isComplete": false,
              "metrics": {
                  "clicks": 4,
                  "impressions": 1036,
                  "reach": 1011,
                  "frequency": 0,
                  "ctr": 0,
                  "cpm": 1.61,
                  "cpp": 1.65,
                  "cpc": 0
              },
              "network": "facebook",
              "postId": "DE6gpw8kxlonHy6eb7L1",
              "spend": 1.67,
              "spendDate": "2025-04-02T00:00:00.000Z",
              "status": "ACTIVE"
          }
      ],
      "dateRange": {
          "start": "2025-02-24T20:02:34.613Z",
          "end": "2025-03-26T20:02:34.613Z",
          "postId": "eSNkaAiFZVin6wm6f"
      },
      "metrics": {
          "totalSpend": 3.25,
          "totalClicks": 7,
          "totalImpressions": 2071,
          "totalReach": 2052,
          "averageCTR": 0.1,
          "averageFrequency": 0,
          "cpm": 0.79,
          "cpp": 0.85,
          "cpc": 0.2,
          "costPerResult": 1.2,
          "byGoalType": {
              "engagement": {
                  "spend": 7.62,
                  "impressions": 9332,
                  "clicks": 0,
                  "reach": 8502,
                  "count": 8,
                  "ctr": 0,
                  "cpm": 0.8165452207458208,
                  "cpp": 0.8962597035991532,
                  "cpc": 0
              }
          },
          "byGoalTitle": {
              "Get More Engagement": {
                  "spend": 3.25,
                  "impressions": 2071,
                  "clicks": 7,
                  "reach": 2052,
                  "count": 1,
                  "type": "engagement",
                  "ctr": 0.1,
                  "cpm": 0.79,
                  "cpp": 0.85,
                  "cpc": 0.2
              }
          },
          "goalPerformance": {
              "bestPerformingGoalType": {
                  "type": "engagement",
                  "clicks": 7,
                  "spend": 3.25,
                  "ctr": 0.1
              },
              "mostEfficientGoalType": {
                  "type": "engagement",
                  "cpc": 0.2,
                  "spend": 3.25
              }
          },
          "count": 2,
          "firstDay": "2025-03-17T00:00:00.000Z",
          "lastDay": "2025-03-23T00:00:00.000Z"
      }
  }
  ```

  ```json 200: Success by Ad ID theme={"system"}
  {
    "status": "success",
    "history": [
      {
        "accountId": "274948332",
        "adId": "6683876017505",
        "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
        "budgetDaily": 4,
        "budgetType": "",
        "deliveryStatus": "ACTIVE",
        "fbPostId": "106638148652329_672633202087926",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 2,
          "cpc": 0,
          "cpp": 1.6,
          "cpm": 1.55,
          "ctr": 0,
          "frequency": 0,
          "impressions": 452,
          "reach": 438
        },
        "network": "facebook",
        "postId": "DE6gpw8kxlonHy6eb7Lo",
        "spend": 0.7,
        "spendDate": "2025-04-03T00:00:00.000Z",
        "status": "ACTIVE"
      },
      {
        "accountId": "274948332",
        "adId": "6683876017505",
        "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
        "budgetDaily": 4,
        "budgetType": "daily",
        "deliveryStatus": "ACTIVE",
        "fbPostId": "106638148652329_672633202087926",
        "goal": {
          "description": "This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.",
          "title": "Get More Engagement",
          "type": "engagement"
        },
        "isActive": true,
        "isComplete": false,
        "metrics": {
          "clicks": 1,
          "cpc": 0,
          "cpp": 1.5,
          "cpm": 1.5,
          "ctr": 0,
          "frequency": 0,
          "impressions": 2793,
          "reach": 2793
        },
        "network": "facebook",
        "postId": "DE6gpw8kxlonHy6eb7Lo",
        "spend": 4.19,
        "spendDate": "2025-04-02T00:00:00.000Z",
        "status": "ACTIVE"
      }
    ],
    "dateRange": {
      "start": "2025-03-04T18:49:18.159Z",
      "end": "2025-04-03T18:49:18.159Z",
      "adId": "6683876017505"
    },
    "metrics": {
      "totalSpend": 4.89,
      "totalClicks": 3,
      "totalImpressions": 10553,
      "totalReach": 10339,
      "averageCTR": 0.03,
      "averageFrequency": 0,
      "cpm": 1.460248270633943,
      "cpp": 1.49047296643776,
      "cpc": 5.136666666666667,
      "costPerResult": 5.14,
      "byGoalType": {
        "engagement": {
          "spend": 4.89,
          "impressions": 10553,
          "clicks": 3,
          "reach": 10339,
          "count": 2,
          "ctr": 0.03,
          "cpm": 1.46,
          "cpp": 1.49,
          "cpc": 5.14
        }
      },
      "byGoalTitle": {
        "Get More Engagement": {
          "spend": 4.89,
          "impressions": 10553,
          "clicks": 3,
          "reach": 10339,
          "count": 2,
          "type": "engagement",
          "ctr": 0.03,
          "cpm": 1.5,
          "cpp": 1.49,
          "cpc": 5.14
        }
      },
      "goalPerformance": {
        "bestPerformingGoalType": {
          "type": "engagement",
          "clicks": 3,
          "spend": 4.89,
          "ctr": 0.03
        },
        "mostEfficientGoalType": {
          "type": "engagement",
          "cpc": 5.14,
          "spend": 4.89
        }
      },
      "count": 2,
      "firstDay": "2025-03-30T00:00:00.000Z",
      "lastDay": "2025-04-03T00:00:00.000Z"
    }
  }
  ```

  ```json 400: Ad spend error theme={"system"}
  {
    "action": "get ad spend",
    "status": "error",
    "code": 367,
    "message": "Error getting ad spend. Please verify you have an active ad account."
  }
  ```
</ResponseExample>