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

> Get Historical Daily Instagram Ad Spend & Analytics

Retrieve detailed daily ad spend and performance metrics for your Instagram 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](/docs/apis/ads/instagram/get-boosted-ads).
>
> 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 Instagram'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>All monetary values are in the ad account's currency (typically USD).</li>
  <li>The `goalPerformance` section highlights your best-performing ad objectives.</li>
</ul>

## Header Parameters

**Authorization** `string` *required*

[API Key](/docs/apis/overview#authorization) of the Primary Profile.

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

[Profile Key](/docs/apis/overview#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](/docs/apis/overview#ayrshare-post-id).

**socialPostId** `string`

Filter results to ads associated with a specific [Instagram social post
ID](/docs/apis/overview#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/instagram/history?accountId=1234567890
```

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

fetch("https://api.ayrshare.com/api/ads/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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",
      "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.29,
        "cpm": 1.53,
        "cpp": 1.54,
        "cpc": 0.53
      },
      "network": "instagram",
      "postId": "DE6gpw8kxlonHy6eb7L1",
      "spend": 1.58,
      "spendDate": "2025-04-02T00:00:00.000Z",
      "status": "ACTIVE",
      "accountId": "274948332"
    },
    {
      "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": 1.02,
        "ctr": 0.39,
        "cpm": 1.61,
        "cpp": 1.65,
        "cpc": 0.42
      },
      "network": "instagram",
      "postId": "DE6gpw8kxlonHy6eb7L1",
      "spend": 1.67,
      "spendDate": "2025-04-02T00:00:00.000Z",
      "status": "ACTIVE",
      "accountId": "274948332"
    }
  ],
  "dateRange": {
    "start": "2025-03-04T18:49:18.159Z",
    "end": "2025-04-03T18:49:18.159Z"
  },
  "metrics": {
    "totalSpend": 3.25,
    "totalClicks": 7,
    "totalImpressions": 2071,
    "totalReach": 2037,
    "averageCTR": 0.34,
    "averageFrequency": 1.02,
    "cpm": 1.57,
    "cpp": 1.6,
    "cpc": 0.46,
    "costPerResult": 0.46,
    "byGoalType": {
      "engagement": {
        "spend": 3.25,
        "impressions": 2071,
        "clicks": 7,
        "reach": 2037,
        "count": 2,
        "ctr": 0.3380009657170449,
        "cpm": 1.5692901979719942,
        "cpp": 1.5954835542464407,
        "cpc": 0.4642857142857143
      }
    },
    "byGoalTitle": {
      "Get More Engagement": {
        "spend": 3.25,
        "impressions": 2071,
        "clicks": 7,
        "reach": 2037,
        "count": 2,
        "ctr": 0.3380009657170449,
        "cpm": 1.5692901979719942,
        "cpp": 1.5954835542464407,
        "cpc": 0.4642857142857143,
        "type": "engagement"
      }
    },
    "goalPerformance": {
      "bestPerformingGoalType": {
        "type": "engagement",
        "clicks": 7,
        "spend": 3.25,
        "ctr": 0.34
      },
      "mostEfficientGoalType": {
        "type": "engagement",
        "cpc": 0.46,
        "spend": 3.25
      }
    },
    "count": 2,
    "firstDay": "2025-04-02T00:00:00.000Z",
    "lastDay": "2025-04-02T00: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",
      "socialPostId": "17890000000000001",
      "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.35,
        "cpp": 1.6,
        "cpm": 1.55,
        "ctr": 0.44,
        "frequency": 1.03,
        "impressions": 452,
        "reach": 438
      },
      "network": "instagram",
      "postId": "DE6gpw8kxlonHy6eb7Lo",
      "spend": 0.7,
      "spendDate": "2025-04-03T00:00:00.000Z",
      "status": "ACTIVE",
      "igPostId": "17890000000000001"
    },
    {
      "accountId": "274948332",
      "adId": "6683876017505",
      "adName": "API Post 13 - DE6gpw8kxlonHy6eb7Lo - 2025-03-30T17:11:26",
      "budgetDaily": 4,
      "budgetType": "daily",
      "deliveryStatus": "ACTIVE",
      "socialPostId": "17890000000000001",
      "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": 4.19,
        "cpp": 1.5,
        "cpm": 1.5,
        "ctr": 0.04,
        "frequency": 1,
        "impressions": 2793,
        "reach": 2793
      },
      "network": "instagram",
      "postId": "DE6gpw8kxlonHy6eb7Lo",
      "spend": 4.19,
      "spendDate": "2025-04-02T00:00:00.000Z",
      "status": "ACTIVE",
      "igPostId": "17890000000000001"
    }
  ],
  "dateRange": {
    "start": "2025-03-04T18:49:18.159Z",
    "end": "2025-04-03T18:49:18.159Z",
    "adId": "6683876017505"
  },
  "metrics": {
    "totalSpend": 4.89,
    "totalClicks": 3,
    "totalImpressions": 3245,
    "totalReach": 3231,
    "averageCTR": 0.09,
    "averageFrequency": 1.02,
    "cpm": 1.51,
    "cpp": 1.51,
    "cpc": 1.63,
    "costPerResult": 1.63,
    "byGoalType": {
      "engagement": {
        "spend": 4.890000000000001,
        "impressions": 3245,
        "clicks": 3,
        "reach": 3231,
        "count": 2,
        "ctr": 0.09244992295839753,
        "cpm": 1.50693374422188,
        "cpp": 1.5134633240482824,
        "cpc": 1.6300000000000001
      }
    },
    "byGoalTitle": {
      "Get More Engagement": {
        "spend": 4.890000000000001,
        "impressions": 3245,
        "clicks": 3,
        "reach": 3231,
        "count": 2,
        "ctr": 0.09244992295839753,
        "cpm": 1.50693374422188,
        "cpp": 1.5134633240482824,
        "cpc": 1.6300000000000001,
        "type": "engagement"
      }
    },
    "goalPerformance": {
      "bestPerformingGoalType": {
        "type": "engagement",
        "clicks": 3,
        "spend": 4.89,
        "ctr": 0.09
      },
      "mostEfficientGoalType": {
        "type": "engagement",
        "cpc": 1.63,
        "spend": 4.89
      }
    },
    "count": 2,
    "firstDay": "2025-04-02T00: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,
    "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": "ads",
  "status": "error",
  "code": 370,
  "message": "Error getting ads. Please try again or contact us if the issue persists.",
  "details": "Error retrieving ads spend data"
}
```


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