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

# History

> Retrieve daily Facebook ad spend and performance metrics for ads created with Boost Post, with goal-specific results, aggregated totals, and date filters.

Retrieve detailed daily ad spend and performance metrics for your Facebook ads.
This endpoint provides comprehensive analytics on your ads with daily breakdowns, goal-specific performance, and aggregated metrics.

> [!TIP]
>
> The `history` array contains historical daily spend and performance metrics
> for each ad. The data is as of 8 AM EST. If real-time spend data is needed or spend has not yet occurred,
> please use the [ads endpoint](https://www.ayrshare.com/docs/apis/ads/facebook/get-boosted-ads.md).
>
> The ad will **NOT** be returned if no spend data is available or spend has not yet occurred.
>
> When no ad has spend in the date range, the response is still a success: `history` is
> empty and `warnings` holds one entry with code `401`.

<ul>
  <li>
    Metrics are calculated from Facebook's reporting API and may have slight delays (up to 24
    hours).
  </li>

  <li>The `byGoalType` and `byGoalTitle` sections group performance metrics by goal objectives.</li>
  <li>Use either `adId` or `postId` filters to narrow results to specific campaigns.</li>
  <li>Each day's `spend` is in the ad account's currency, shown in `currency`. `spendUsd` is the same spend in US dollars.</li>
  <li>Non-USD spend is converted to USD at that day's exchange rate from Open Exchange Rates. `totalSpend`, `cpm`, `cpp`, `cpc`, `costPerResult` and the goal `spend` totals are in US dollars.</li>
  <li>`totalSpendByCurrency` gives the total spend in each currency before conversion. `unconvertedRows` counts the days not converted yet: they count at face value in `totalSpend`, and their `spendUsd` is `null`.</li>
  <li>Spend from before October 2026 may show `currency: "USD"` even when the ad account uses another currency, and is counted in `totalSpend` as recorded.</li>
  <li>The `goalPerformance` section highlights your best-performing ad objectives.</li>
</ul>

> [!NOTE]
>
> This endpoint only returns Facebook ads created via the [Boost Post](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md)
> endpoint. Ads created in Facebook Ads Manager or other third-party tools are not returned.

## Header Parameters

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## Query Parameters

**accountId** `string`

Filter results to a specific account ID.

**adId** `string`

Filter results to a specific ad ID.

**postId** `string`

Filter results to ads associated with a specific [Ayrshare post
ID](https://www.ayrshare.com/docs/apis/overview.md#ayrshare-post-id).

**fbPostId** `string`

Filter results to ads associated with a specific [Facebook social post
ID](https://www.ayrshare.com/docs/apis/overview.md#social-post-id).

**limit** `number` (default: 25)

Retrieve a maximum of `limit` ads. Maximum is 300; higher values are capped at 300.

**startDate** `string` (default: 30 days ago)

Start date for the reporting period in ISO 8601 format (default: 30 days ago)

**endDate** `string` (default: today)

End date for the reporting period in ISO 8601 format (default: today)

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

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

fetch("https://api.ayrshare.com/api/ads/facebook/history?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/history', 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/history",
    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/history");
        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/history", 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/history"))
            .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/history')

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

```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",
            "currency": "USD",
            "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": 1.01,
                "ctr": 0,
                "cpm": 1.53,
                "cpp": 1.54,
                "cpc": 0
            },
            "network": "facebook",
            "postId": "DE6gpw8kxlonHy6eb7L1",
            "spend": 1.58,
            "spendDate": "2025-04-02T00:00:00.000Z",
            "spendUsd": 1.58,
            "status": "ACTIVE"
        },
        {
            "adId": "120218167147110411",
            "adName": "API Post 2 - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T16:41:15",
            "budgetDaily": 4,
            "budgetType": "daily",
            "currency": "USD",
            "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": 1.02,
                "ctr": 0,
                "cpm": 1.61,
                "cpp": 1.65,
                "cpc": 0
            },
            "network": "facebook",
            "postId": "DE6gpw8kxlonHy6eb7L1",
            "spend": 1.67,
            "spendDate": "2025-04-02T00:00:00.000Z",
            "spendUsd": 1.67,
            "status": "ACTIVE"
        }
    ],
    "dateRange": {
        "start": "2025-02-24T20:02:34.613Z",
        "end": "2025-03-26T20:02:34.613Z",
        "postId": "eSNkaAiFZVin6wm6f"
    },
    "metrics": {
        "totalSpend": 3.25,
        "totalSpendByCurrency": { "USD": 3.25 },
        "unconvertedRows": 0,
        "totalClicks": 7,
        "totalImpressions": 2071,
        "totalReach": 2052,
        "averageCTR": 0.1,
        "averageFrequency": 1.02,
        "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": "",
      "currency": "USD",
      "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": 1.03,
        "impressions": 452,
        "reach": 438
      },
      "network": "facebook",
      "postId": "DE6gpw8kxlonHy6eb7Lo",
      "spend": 0.7,
      "spendDate": "2025-04-03T00:00:00.000Z",
      "spendUsd": 0.7,
      "status": "ACTIVE"
    },
    {
      "accountId": "274948332",
      "adId": "6683876017505",
      "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
      "budgetDaily": 4,
      "budgetType": "daily",
      "currency": "USD",
      "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": 1,
        "impressions": 2793,
        "reach": 2793
      },
      "network": "facebook",
      "postId": "DE6gpw8kxlonHy6eb7Lo",
      "spend": 4.19,
      "spendDate": "2025-04-02T00:00:00.000Z",
      "spendUsd": 4.19,
      "status": "ACTIVE"
    }
  ],
  "dateRange": {
    "start": "2025-03-04T18:49:18.159Z",
    "end": "2025-04-03T18:49:18.159Z",
    "adId": "6683876017505"
  },
  "metrics": {
    "totalSpend": 4.89,
    "totalSpendByCurrency": { "USD": 4.89 },
    "unconvertedRows": 0,
    "totalClicks": 3,
    "totalImpressions": 10553,
    "totalReach": 10339,
    "averageCTR": 0.03,
    "averageFrequency": 1.02,
    "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 200: No spend data theme={"system"}
{
  "status": "success",
  "history": [],
  "dateRange": {
    "start": "2025-03-04T18:49:18.159Z",
    "end": "2025-04-03T18:49:18.159Z",
    "adId": "6683876017505"
  },
  "metrics": {
    "totalSpend": 0,
    "totalSpendByCurrency": {},
    "unconvertedRows": 0,
    "totalClicks": 0,
    "totalImpressions": 0,
    "totalReach": 0,
    "averageCTR": 0,
    "averageFrequency": 0,
    "cpm": 0,
    "cpp": 0,
    "cpc": 0,
    "costPerResult": 0,
    "byGoalType": {},
    "byGoalTitle": {},
    "goalPerformance": {
      "bestPerformingGoalType": null,
      "mostEfficientGoalType": null
    },
    "daysCount": 0,
    "firstDay": null,
    "lastDay": null
  },
  "warnings": [
    {
      "action": "ads",
      "status": "error",
      "code": 401,
      "message": "No spend data found for the ad."
    }
  ]
}
```

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


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