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