curl -X POST https://api.ayrshare.com/api/ads/instagram/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/instagram/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/instagram/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/instagram/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/instagram/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/instagram/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/instagram/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
payload.put("locations", Map.of("countries", Arrays.asList("US")));
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/instagram/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": {"countries": ["US"]},
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"socialPostId": "1234567890",
"igPostId": "1234567890",
"platform": "instagram",
"startDate": "2026-03-26T22:30:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: accountId"
}
Instagram Ads
Boost Post
Boost a post by submitting it to Instagram’s ad platform
POST
/
ads
/
instagram
/
boost
curl -X POST https://api.ayrshare.com/api/ads/instagram/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/instagram/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/instagram/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/instagram/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/instagram/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/instagram/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/instagram/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
payload.put("locations", Map.of("countries", Arrays.asList("US")));
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/instagram/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": {"countries": ["US"]},
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"socialPostId": "1234567890",
"igPostId": "1234567890",
"platform": "instagram",
"startDate": "2026-03-26T22:30:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: accountId"
}
Boost an existing Instagram post to create an ad.
This endpoint allows you to convert your organic posts into paid advertisements with custom targeting, budget, and scheduling parameters.
The
Replace the example IDs with your own. Set
- Budget and bid amounts must be specified in USD with up to two decimal places.
- The ad must run for at least 30 hours to address the Instagram requirement.
- You can use the interests endpoint to find interest IDs for targeting.
- Instagram may take up to 24 hours to review and approve boosted posts.
- If using
socialPostIddirectly (instead of AyrsharepostId), ensure it’s a valid Instagram post ID. - If a boost fails after Facebook has created its campaign (at the creative, ad set or ad step), we try to delete that campaign. If the delete also fails, the empty campaign stays in your ad account. You can find and delete it in Ads Manager.
Meta refuses the ad until both of these are in place:
- A payment method on the ad account. Add one in Meta’s Billing & payments and attach it to the ad account you send as
accountId. A payment method saved only on the business portfolio is not enough. - Personalized ads turned on (EU, EEA and Switzerland). If the owner of the Facebook or Instagram account linked to your Facebook Page chose to see less-personalized ads, or subscribed to use Meta without ads, Meta does not let that account or the Page run ads. The owner can switch back to personalized ads, or cancel the subscription, in Accounts Center → Ad preferences → Ad experience. Learn more.
Ad Goals
Each ad must have a goal. The goal determines how the ad will be optimized for display.engagement: 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.interactions: Designed to boost interactions, such as likes, comments, and shares, on the ad. Instagram prioritizes showing the ad to users most likely to engage with it.awareness_views: Focuses on increasing brand awareness by maximizing the number of times the ad is displayed. It prioritizes showing the ad as many times as possible within the budget, regardless of unique reach.awareness_audience: Aims to enhance brand awareness by maximizing the number of unique people who see the ad. It ensures that the ad reaches as many different users as possible and maximizes the unique audience size rather than showing it multiple times to the same audience.
Instagram ads require an Instagram Business account connected through Facebook, an associated Facebook Page, and the
ads_management permission. Relink through Facebook to grant this permission. Accounts connected with Instagram Login cannot use these ads endpoints. The media ID and Instagram account ID are resolved from your linked account; do not send instagram_user_id.socialPostId selector also accepts the Instagram-specific alias igPostId. fbPostId applies only to Facebook. Successful responses include platform: "instagram", socialPostId, and igPostId.
Header Parameters
Body Parameters
string
A unique, non-empty key for this boost request. Retry the same payload with the same key to avoid creating a duplicate ad. Reusing the key with a different payload or platform returns HTTP 409. A request still in progress also returns 409; an unavailable reservation returns 503 without creating an ad.
boolean
default:false
Allow Meta to share budget between ad sets in the campaign.
string
required
The ID of the Instagram ad account to boost the post on. The account ID can be retrieved from the
ad accounts endpoint.
string
required
Name for your ad (appears in Instagram Ad Manager) with the format
{adName} - {postId or socialPostId} - {current date}.number
required
Maximum bid amount in USD, as a positive amount with up to two decimal places.
number
required
Daily budget in USD. Use a positive amount with up to two decimal places. Meta may enforce additional minimums for your account and goal.
string
The Instagram social post ID of the post to boost, which allows
you to create an ad from a post created directly on Instagram. This is the ID of the post on
Instagram, not Ayrshare. Required if
postId is not set.string
default:"engagement"
The goal of the ad. Values:
engagement, interactions, awareness_views, and
awareness_audience. See ad goals details above for
more information.object
Target countries with
{"countries": ["US", "CA"]} using country codes. You can also supply regions and cities arrays; see regions and cities. An object that names no country, region or city, such as {}, is refused with code 101; leave locations out to target the US.string
The Ayrshare post ID of the post to boost. Required if
socialPostId is not set.string
default:"active"
The status of the ad. Values:
active and paused.You can later change the status of the ad using the update ad endpoint.object
Track the ad using a Meta Pixel.
Show child attributes
Show child attributes
number
required
The ID of the Meta Pixel to track the ad.
{
"pixelId": 1234567890
}
array
Add UTM tags to the ad URL.For example if the linking URL is
{
"urlTags": ["utm_source=ayrshare", "utm_medium=social", "utm_campaign=ayrshare-social"]
}
https://www.mysite.com/my-post and the URL tags added are:utm_source=ayrshare, utm_medium=social, and utm_campaign=ayrshare-social.The ad URL will be:
https://www.mysite.com/my-post?utm_source=ayrshare&utm_medium=social&utm_campaign=ayrshare-social.array
Meta requires advertisers in special ad categories to self-identify their campaign category.If your business is in one of these categories, you must select the appropriate category when boosting your post.The following values are supported:
housing: Ads that promote or directly link to a housing opportunity or related service, including but not limited to listings for the sale or rental of a home or apartment, homeowners insurance, mortgage insurance, mortgage loans, housing repairs and home equity or appraisal services.financial_product_services: Ads that promote or directly link to a financial products and services offer, including credit.employment: Ads that promote or directly link to an employment opportunity, including but not limited to part- or full-time jobs, internships or professional certification programs. Related ads that fall within this category include promotions for job boards or fairs, aggregation services or ads detailing perks a company may provide, regardless of a specific job offer.issues_elections_politics: Ads made by, on behalf of, or about a candidate for public office, a political figure, a political party or advocating for the outcome of an election to public office. This also includes ads about any election, referendum or ballot initiative, including “Go out and vote” election campaigns. Ads regulated as political advertising or about social issues in any place where the ad is being placed. If selecting issues, elections, or politics, you must select the country in which you want to run these ads. You are required to be authorized to run ads about social issues, elections, or politics in the specified country.
locations: the countries you list, plus the country of each region and city. So a housing boost that targets a city in the UK is set up for the UK, with nothing extra in your request. Without locations the ad runs in the US, and the campaign is set up for the US.Meta also sets a minimum radius around each city for these categories. A UK city with a 17 kilometer radius was rejected with #2909039, which asks for at least 25 kilometers (15 miles), so use 25 kilometers or more.Meta requires advertisers to identify their campaign category correctly.
Meta uses human reviewers and machine-learning to identify these kinds of ads.
If you send us an incorrect
specialAdCategories, there is a risk your ads will be paused until the campaign is adjusted.string
The person or organization benefiting from the ad. Set together with
dsaPayor. Use the DSA recommendations endpoint for suggestions.string
The person or organization paying for the ad. Set together with
dsaBeneficiary.string
End date and time in ISO 8601 format (must be at least 30 hours after start), for example
2025-03-01T00:00:00Z.If not set, the ad will run indefinitely and have end date of ongoing.object
Exclude locations using the same
countries, regions, and cities structure as locations.string
default:"all"
The gender of the audience. Values:
all, male, female.array
The target interests of the ad as an array of Instagram interest
ids.
number
default:65
Maximum age for targeting the ad (default: 65).
number
default:18
Minimum age for targeting the ad (default: 18).
string
Start date and time in ISO 8601 format, for example
2025-03-01T00:00:00Z.If not set, the ad will start immediately.startDate and endDate to your intended schedule; the example dates are illustrative.
Lifetime Budgets
The body above sets a daily budget on the ad set. For a lifetime budget, send the nested form of the boost body instead. In the nested form,accountId, postId (or socialPostId in place of igPostId), goal, status and callToAction stay at the top level. Three objects replace the flat budget, date and targeting fields: budget, schedule (start, end) and targeting (locations, excludedLocations, ageMin, ageMax, genders, interests). The remaining fields, adName, bidAmount, specialAdCategories, adSetBudgetSharingEnabled, link, tracking, urlTags, dsaBeneficiary and dsaPayor, move under platformOptions.instagram.
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"budget": { "amount": 50, "type": "lifetime" },
"schedule": { "start": "2026-11-01T00:00:00Z", "end": "2026-11-08T00:00:00Z" },
"targeting": { "ageMin": 25, "ageMax": 45, "locations": { "countries": ["US"] } },
"platformOptions": { "instagram": { "adName": "November boost", "bidAmount": 2 } }
}
budget.type:daily(the default) orlifetime. A lifetime budget is spent between the start and end dates, so it needsschedule.end. Without one the request is rejected with a400andcode: 101. Meta’s ad set budget sharing works with daily budgets only, so a lifetime budget withadSetBudgetSharingEnabled: trueis also rejected withcode: 101.
budgetType: "lifetime" for a lifetime budget. A daily budget does not return budgetType, so treat a missing field as daily.
Campaign Budgets
To hold the budget on the campaign instead of the ad set, sendbudget.level: "campaign" in the nested form shown above. The ad set then has no budget of its own. It works with daily and lifetime budgets.
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"budget": { "amount": 50, "type": "lifetime", "level": "campaign" },
"schedule": { "start": "2026-11-01T00:00:00Z", "end": "2026-11-08T00:00:00Z" },
"platformOptions": { "instagram": { "adName": "November boost", "bidAmount": 2 } }
}
budget.level:adSet(the default) orcampaign. A campaign budget cannot be combined withadSetBudgetSharingEnabled. Sending both is rejected with a400andcode: 101.- The response adds
budgetLevel: "campaign"for a campaign budget. An ad set budget does not returnbudgetLevel, so treat a missing field asadSet. - In History,
budgetDailyshows the campaign’s daily budget for an ad with a daily campaign budget. If several ads share one campaign budget, each shows the whole campaign budget, not its share. History does not show lifetime budgets, on the campaign or the ad set. Once a lifetime campaign budget is spent, every ad in that campaign showsdeliveryStatus: "COMPLETED"after the next nightly update, including an ad that is scheduled or in review. A rejected ad staysREJECTED.
Boost into an Existing Campaign or Ad Set
By default every boost creates its own campaign, ad set and ad. To add the boost to a campaign or ad set you already run in Meta, send the nested form withattachTo.
attachTo.campaignId: the boost creates a new ad set and ad inside that campaign. Sendbudget,targetingandbidAmountas usual: they apply to the new ad set.attachTo.adSetId: the boost creates only the ad, inside that ad set. Also sendattachTo.campaignId, the campaign the ad set belongs to. Leave outbudget,targetingandplatformOptions.instagram.bidAmount: the ad set keeps its own. Sending any of them returns a400withcode: 101.
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"attachTo": { "campaignId": "120210000000000001", "adSetId": "120210000000000002" },
"platformOptions": { "instagram": { "adName": "November boost" } }
}
- The campaign or ad set must be in the ad account named by
accountId, and must not belong to another user’s boosts. Otherwise the request returns a400. An Instagram boost also cannot attach to a campaign a Facebook boost created, and the reverse. attachTocannot be combined withbudget.level: "campaign",specialAdCategoriesoradSetBudgetSharingEnabled, which are set on a new campaign. Sending them returnscode: 101.- Pausing or activating the boost changes only what the boost created: the ad, and the ad set when the boost created it. The campaign or ad set you named in
attachTokeeps its own status. The ad runs only while the campaign and ad set above it are active. This also applies when Ayrshare pauses your ads, for example when a profile is deleted. - If the boost fails, the campaign or ad set named in
attachTois never deleted. - If the ad set you attach to sits in a campaign that holds the budget (a campaign budget), History reports the boost like any ad with a campaign budget:
budgetDailyshows the whole campaign budget, not the boost’s share, and once a lifetime campaign budget is spent, every ad Ayrshare tracks in that campaign showsdeliveryStatus: "COMPLETED"after the next nightly update, including an ad that is scheduled or in review. A rejected ad staysREJECTED.
Open a Conversation Instead of a Link
A boost’s button can open a chat with your business instead of a web page. Send the nested form withcallToAction.destination, and leave out callToAction.link.
destination | Opens | callToAction.type |
|---|---|---|
messenger | Messenger | MESSAGE_PAGE |
whatsapp | WHATSAPP_MESSAGE | |
instagramDm | Instagram Direct | INSTAGRAM_MESSAGE |
{
"accountId": "123456789",
"postId": "Ut1fWU6XkqkMayHGnJZ",
"goal": "engagement",
"budget": { "amount": 20 },
"callToAction": { "type": "WHATSAPP_MESSAGE", "destination": "whatsapp" },
"platformOptions": { "instagram": { "adName": "Chat with us", "bidAmount": 2 } }
}
- Use the
engagementorinteractionsad goal. The ad is then optimized for conversations: Meta shows it to people likely to start a chat. Other goals return a400withcode: 101. callToAction.typemust match the destination, as in the table. Any casing is accepted.callToAction.linkandcallToAction.linkTitlecannot be sent withdestination, because the button opens a chat, not a page. Withoutdestination,linkis still required.- People message the account linked to your profile. For
whatsapp, its Facebook Page must have a WhatsApp Business number connected in Meta. destinationcannot be combined withattachTo.adSetId: the existing ad set keeps the destination it already has. WithattachTo.campaignId, the campaign must have Meta’sOUTCOME_ENGAGEMENTobjective; otherwise the request returns a400withcode: 101.- The response, and Get Boosted Ads, return
callToActionwith itsdestination. Meta stores the same settings for both goals, so a chat button boosted withinteractionscan be listed with theengagementgoal when the ad is read back from Meta.
curl -X POST https://api.ayrshare.com/api/ads/instagram/boost \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-d '{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}'
const API_KEY = "API_KEY";
fetch("https://api.ayrshare.com/api/ads/instagram/boost", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${API_KEY}`
},
body: JSON.stringify({
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
})
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
import requests
API_KEY = "API_KEY"
url = "https://api.ayrshare.com/api/ads/instagram/boost"
payload = {
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": {"countries": ["US"]},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": [1234567890, 1234567891]
}
response = requests.post(url, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json=payload)
print(response.json())
<?php
$API_KEY = "API_KEY";
$payload = [
"postId" => "1234567890",
"accountId" => "1234567890",
"adName" => "My Ad",
"status" => "active",
"goal" => "engagement",
"minAge" => 18,
"maxAge" => 65,
"locations" => ["countries" => ["US"]],
"budget" => 100,
"bidAmount" => 1,
"startDate" => "2025-03-01T00:00:00Z",
"endDate" => "2025-03-07T23:59:59Z",
"interests" => [1234567890, 1234567891]
];
$ch = curl_init("https://api.ayrshare.com/api/ads/instagram/boost");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Content-Type: application/json",
"Authorization: Bearer " . $API_KEY
]);
$response = curl_exec($ch);
$result = json_decode($response, true);
print_r($result);
curl_close($ch);
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string API_KEY = "API_KEY";
var payload = new
{
postId = "1234567890",
accountId = "1234567890",
adName = "My Ad",
status = "active",
goal = "engagement",
minAge = 18,
maxAge = 65,
locations = new { countries = new[] { "US" } },
budget = 100,
bidAmount = 1,
startDate = "2025-03-01T00:00:00Z",
endDate = "2025-03-07T23:59:59Z",
interests = new[] { 1234567890, 1234567891 }
};
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", API_KEY);
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.ayrshare.com/api/ads/instagram/boost", content);
var responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseBody);
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiKey := "API_KEY"
payload := map[string]interface{}{
"postId": "1234567890",
"accountId": "1234567890",
"adName": "My Ad",
"status": "active",
"goal": "engagement",
"minAge": 18,
"maxAge": 65,
"locations": map[string]interface{}{"countries": []string{"US"}},
"budget": 100,
"bidAmount": 1,
"startDate": "2025-03-01T00:00:00Z",
"endDate": "2025-03-07T23:59:59Z",
"interests": []int{1234567890, 1234567891},
}
jsonData, err := json.Marshal(payload)
if err != nil {
fmt.Println("Error marshaling JSON:", err)
return
}
req, err := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/instagram/boost", bytes.NewBuffer(jsonData))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response:", err)
return
}
fmt.Println(string(body))
}
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class BoostPost {
public static void main(String[] args) {
String API_KEY = "API_KEY";
String url = "https://api.ayrshare.com/api/ads/instagram/boost";
Map<String, Object> payload = new HashMap<>();
payload.put("postId", "1234567890");
payload.put("accountId", "1234567890");
payload.put("adName", "My Ad");
payload.put("status", "active");
payload.put("goal", "engagement");
payload.put("minAge", 18);
payload.put("maxAge", 65);
payload.put("locations", Map.of("countries", Arrays.asList("US")));
payload.put("budget", 100);
payload.put("bidAmount", 1);
payload.put("startDate", "2025-03-01T00:00:00Z");
payload.put("endDate", "2025-03-07T23:59:59Z");
payload.put("interests", Arrays.asList(1234567890, 1234567891));
try {
ObjectMapper objectMapper = new ObjectMapper();
String requestBody = objectMapper.writeValueAsString(payload);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (IOException | InterruptedException e) {
e.printStackTrace();
}
}
}
require 'net/http'
require 'uri'
require 'json'
API_KEY = "API_KEY"
uri = URI.parse("https://api.ayrshare.com/api/ads/instagram/boost")
payload = {
postId: "1234567890",
accountId: "1234567890",
adName: "My Ad",
status: "active",
goal: "engagement",
minAge: 18,
maxAge: 65,
locations: { countries: ["US"] },
budget: 100,
bidAmount: 1,
startDate: "2025-03-01T00:00:00Z",
endDate: "2025-03-07T23:59:59Z",
interests: [1234567890, 1234567891]
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{API_KEY}"
request.body = payload.to_json
response = http.request(request)
puts response.body
{
"status": "success",
"adId": "120217670757750410",
"adName": "API Post - DE6gpw8kxlonHy2b7Lo - 2025-03-26T23:42:43",
"adStatus": "active",
"bidAmount": 10,
"budget": 100,
"endDate": "2026-03-28T22:30:00Z",
"goal": {
"title": "Get More Engagement",
"description": "This goal seeks to increase engagement...",
"type": "engagement"
},
"interests": [
"6003195554098"
],
"locations": {"countries": ["US"]},
"maxAge": 65,
"minAge": 18,
"postId": "DE6gpw8kxlonHy2b7Lo",
"socialPostId": "1234567890",
"igPostId": "1234567890",
"platform": "instagram",
"startDate": "2026-03-26T22:30:00Z"
}
{
"action": "boost post",
"status": "error",
"code": 369,
"message": "Unable to boost post. Please try again or contact us if the issue persists.",
"details": "The accountId likely does not exist. Please check the accountId and try again."
}
{
"action": "request",
"status": "error",
"code": 101,
"message": "Missing or incorrect parameters. Please verify with the docs. https://www.ayrshare.com/docs/apis",
"details": "Missing required fields: accountId"
}