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

# Histórico

> Obter gasto diário histórico e análises de anúncios do 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} />

Recupere gastos diários detalhados de anúncios e métricas de desempenho para seus anúncios do Facebook.
Este endpoint fornece análises abrangentes sobre seus anúncios com detalhamentos diários, desempenho específico por objetivo e métricas agregadas.

<Tip>
  O array `dailySpend` contém métricas históricas diárias de gasto e desempenho
  para cada anúncio. Os dados estão atualizados até as 8h EST. Se forem necessários dados de gasto em tempo real ou o gasto ainda não tiver ocorrido,
  utilize o [endpoint de anúncios](/apis/ads/facebook/get-boosted-ads).

  O anúncio **NÃO** será retornado se não houver dados de gasto disponíveis ou se o gasto ainda não tiver ocorrido.
</Tip>

<ul className="custom-bullets">
  <li>
    As métricas são calculadas a partir da API de relatórios do Facebook e podem ter pequenos atrasos (até 24
    horas).
  </li>

  <li>As seções `byGoalType` e `byGoalTitle` agrupam métricas de desempenho por objetivos.</li>
  <li>Use os filtros `adId` ou `postId` para restringir os resultados a campanhas específicas.</li>
  <li>Todos os valores monetários estão na moeda da conta de anúncios (normalmente USD).</li>
  <li>A seção `goalPerformance` destaca seus objetivos de anúncio de melhor desempenho.</li>
</ul>

<Info>
  Este endpoint retorna apenas anúncios do Facebook criados por meio do endpoint [Boost Post](/apis/ads/facebook/boost-post).
  Anúncios criados no Gerenciador de Anúncios do Facebook ou em outras ferramentas de terceiros não são retornados.
</Info>

## Parâmetros de cabeçalho

<HeaderAPI />

## Parâmetros de consulta

<ParamField query="accountId" type="number">
  Filtra os resultados por um ID de conta específico.
</ParamField>

<ParamField query="adId" type="string">
  Filtra os resultados por um ID de anúncio específico.
</ParamField>

<ParamField query="postId" type="string">
  Filtra os resultados por anúncios associados a um [ID de publicação da
  Ayrshare](/apis/overview#ayrshare-post-id) específico.
</ParamField>

<ParamField query="fbPostId" type="string">
  Filtra os resultados por anúncios associados a um [ID de publicação social do
  Facebook](/apis/overview#social-post-id) específico.
</ParamField>

<ParamField query="limit" type="number" default={25}>
  Recupera no máximo `limit` anúncios. O máximo é 500.
</ParamField>

<ParamField query="startDate" type="string" default="30 days ago">
  Data de início do período de relatório no formato ISO 8601 (padrão: 30 dias atrás)
</ParamField>

<ParamField query="endDate" type="string" default="today">
  Data de término do período de relatório no formato ISO 8601 (padrão: hoje)
</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>