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

# Boosted Ads

> Get boosted ads from your Instagram account

Retrieve ads that have been boosted for a specific Instagram post.

This boosted ads endpoint provides detailed information about the boosted ads, including status, current spend, performance metrics (analytics), and preview links.

<ul>
  <li>
    The metrics are real-time totals for the ads. If you need historical data, use the [get ad
    history endpoint](/docs/apis/ads/instagram/get-ad-history).
  </li>

  <li>
    `review` is Meta's review of the ad: `status` is `pending` while Meta reviews it, `rejected`
    when Meta disapproved it or left policy feedback on it, and `approved` when the ad is
    active or pre-approved. `reasons` holds Meta's explanations, or the policy's name when Meta gives no text, and is empty when there is no feedback. `review` is `null` when neither
    the ad's status nor any feedback shows the review, for example an ad paused before review.
  </li>

  <li>
    The `previewLink` URL allows you share the preview ad with your colleagues, so that they will
    see the ad for 24-hours across the various Instagram formats. Your colleagues' views of the ad
    will not be counted towards your ad spend.
  </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` *required*

Retrieve all ads under the account ID.

The ad account id, with or without the `act_` prefix (`1234567890` or `act_1234567890`).

Required if `adId`, `socialPostId`, or `postId` is not set.

**adId** `string` *required*

Retrieve an ad with the ad ID.

Required if `accountId`, `socialPostId`, or `postId` is not set.

**socialPostId** `string` *required*

Retrieve ads with the [Instagram social post ID](/docs/apis/overview#social-post-id).

Required if `accountId`, `adId`, or `postId` is not set.

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

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

**postId** `string` *required*

Retrieve ads with the [Ayrshare post ID](/docs/apis/overview#ayrshare-post-id).

Required if `accountId`, `adId`, or `socialPostId` is not set.

**status** `string` (default: all)

Filter ads by status of the ad. Omit this parameter to return ads of every
status. Valid values are:

<ul>
  <li>`active`</li>
  <li>`paused`</li>
  <li>`deleted`</li>
  <li>`archived`</li>
</ul>

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

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

fetch("https://api.ayrshare.com/api/ads/instagram/ads?adId=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/ads?adId=1234567890', headers=headers)

print(r.json())
```

```php PHP theme={"system"}
<?php

$apiUrl = 'https://api.ayrshare.com/api/ads/instagram/ads?adId=1234567890';
$apiKey = 'API_KEY';  // Replace 'API_KEY' with your actual API key

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
];

$curl = curl_init($apiUrl);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($curl);

if ($response === false) {
    echo 'Curl error: ' . curl_error($curl);
} else {
    echo json_encode(json_decode($response), JSON_PRETTY_PRINT);
}

curl_close($curl);

```

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

namespace HistoryGETRequest_csharp
{
class History
{
    static async Task Main(string[] args)
    {
        string API_KEY = "API_KEY";
        string url = "https://api.ayrshare.com/api/ads/instagram/ads?adId=1234567890";

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + API_KEY);

            try
            {
                var response = await client.GetStringAsync(url);
                Console.WriteLine(response);
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"Error: {ex.Message}");
            }
        }
    }
}
}
```

```json 200: Success with Ad ID theme={"system"}
{
    "status": "success",
    "ads": [
        {
            "postId": "DE6gpw8kxlonHy6eb721",
            "ad": {
                "accountId": "274948331",
                "adId": "6683876017501",
                "budgetRemaining": 0,
                "created": "2025-03-30T10:11:34-0700",
                "creativeId": "1033490148629541",
                "dailyBudget": 0,
                "deliveryStatus": "ACTIVE",
                "endDate": "2025-04-03T22:30:00.000Z",
                "socialPostId": "106638148652329",
                "goal": {
                    "title": "Get More Engagement",
                    "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.",
                    "type": "engagement"
                },
                "isComplete": false,
                "lifetimeBudget": 0,
                "metrics": {
                    "spend": 9.21,
                    "impressions": 6495,
                    "reach": 6272,
                    "clicks": 3,
                    "ctr": 0.046189,
                    "cpm": 1.418014,
                    "cpp": 1.468431,
                    "frequency": 1.035555,
                    "uniqueClicks": 3,
                    "uniqueCtr": 0.047832,
                    "costPerUniqueClick": 3.07,
                    "inlineLinkClicks": 0,
                    "costPerInlineLinkClick": 0,
                    "outboundClicks": 0,
                    "costPerOutboundClick": 0,
                    "websiteCtr": [],
                    "accountCurrency": "USD",
                    "accountName": "John Doe",
                    "accountId": "274948331"
                },
                "name": "API Post - DE6gpw8kxlonHy6eb7L1 - 2025-03-30T17:11:26",
                "previewLink": "https://fb.me/22Cn31wXlzhxOC1",
                "review": {
                    "reasons": [],
                    "status": "approved"
                },
                "spend": 9.21,
                "startDate": "2025-03-30T17:11:32.000Z",
                "status": "ACTIVE",
                "targeting": {
                    "ageMax": 65,
                    "ageMin": 18,
                    "geoLocations": {
                        "countries": [
                            "US"
                        ],
                        "locationTypes": [
                            "home",
                            "recent"
                        ]
                    },
                    "interests": [
                        {
                            "id": "6003195554098",
                            "name": "Rhythm and blues music"
                        }
                    ]
                }
            }
        }
    ],
    "count": 1
}
```

```json 400: Boosted ads error theme={"system"}
{
  "action": "ads",
  "status": "error",
  "code": 370,
  "message": "Error getting ads. Please try again or contact us if the issue persists."
}
```


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