> ## 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. # Interests > Get Facebook Ad Interests 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 Available on {displayPlans.length === 1 ? "the " : ""} {displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "} {displayPlans.length > 1 ? "plans" : "plan"}. {maxPackRequired && window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer"> Max Pack required } ; }; export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <> API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY {!noProfileKey && (profileKeyRequired ? Profile Key of a User Profile.

Format: Profile-Key: PROFILE_KEY : Profile Key of a User Profile.

Format: Profile-Key: PROFILE_KEY )} ; Search for available Facebook ad targeting interests by keyword. Use this endpoint to look up interest IDs for the [Boost Post](/docs/apis/ads/facebook/boost-post) endpoint. This endpoint helps you discover interest-based targeting options for your Facebook ads, along with audience size estimates. ## Header Parameters ## Query Parameters The search query to retrieve Facebook ad interests. Don't forget to escape the search query, for example `Rhythm%20and%20blues%20music`. Restrict the results to the interests Meta allows a [special ad category](/docs/apis/ads/facebook/boost-post#param-special-ad-categories) campaign to target. Use this before boosting a housing, employment, financial, or political post so you pick interest IDs the ad will actually be approved for. The following values are supported, matching the [Boost Post](/docs/apis/ads/facebook/boost-post#param-special-ad-categories) parameter of the same name:
  • `housing`
  • `employment`
  • `financial_product_services` — `financial_products_services` and `credit` are accepted as equivalents and resolve to the same category
  • `issues_elections_politics`
  • `none` — accepted for symmetry with [Boost Post](/docs/apis/ads/facebook/boost-post#param-special-ad-categories), where it means "not in a special ad category". It is sent to Meta as `regulated_categories=["NONE"]`: `accountId` is required and a successful response echoes `["NONE"]`. This does not guarantee the same results as an unfiltered search; a Meta rejection returns `code: 368`. Omit `specialAdCategories` entirely rather than sending `none` if you want an ordinary unfiltered search.
Values are case-insensitive. An unrecognized value is rejected with a `400` and `code: 101` listing the accepted values. That message is written in Meta's upper-case form and also names the alternative spellings above, so it reads `NONE, HOUSING, FINANCIAL_PRODUCTS_SERVICES, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCT_SERVICES, CREDIT` — the same categories listed here, not extra ones. Boost Post returns the identical message. An empty value, as in `?specialAdCategories=`, is rejected the same way. Pass more than one category by repeating the parameter, for example `?search=nursing&specialAdCategories=employment&specialAdCategories=housing`. The bracketed form `?specialAdCategories[]=employment&specialAdCategories[]=housing` works as well. A comma-separated string such as `?specialAdCategories=employment,housing` is **not** supported and is rejected with a `400` and `code: 101`. All requested categories are sent to Meta in one search. Ayrshare returns Meta's results and does not compute or guarantee an intersection of independently eligible interests. Repeating a category, or sending two spellings of the same one, collapses to a single category. When you supply more than one category, the `specialAdCategories` field echoed back in the response is sorted alphabetically rather than returned in the order you sent it. Omit `specialAdCategories` entirely and the endpoint behaves exactly as it did before: an unfiltered search, no `accountId` needed, and the same response shape. Required when `specialAdCategories` is supplied, and ignored otherwise. The ID of the Facebook ad account the interests are being searched for, without the `act_` prefix — the same value [Boost Post](/docs/apis/ads/facebook/boost-post) takes. Retrieve it from the [ad accounts endpoint](/docs/apis/ads/facebook/get-ad-accounts). It must be numeric; a leading `act_` is accepted and stripped, and anything else is rejected with a `400` and `code: 101`. Meta only offers category-aware interest search on an ad account, so a request that supplies `specialAdCategories` without `accountId` is rejected with a `400` and `code: 101` before any search runs. A request with no `specialAdCategories` is unchanged and still needs no `accountId`. Limit the number of ad interests returned. A filtered response echoes the applied categories back in a `specialAdCategories` field, so you can confirm what the results were narrowed against. An unfiltered response omits that field entirely rather than returning it empty. Filtered results also omit the `topic` field on each interest, because Meta's category-aware search does not return it — read `name` instead. A search with no eligible interests returns `200` with an empty `interests` array and `count: 0`, not an error, and a filtered search never falls back to unfiltered results. ```bash cURL theme={"system"} curl \ -H "Authorization: Bearer API_KEY" \ -X GET https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music ``` ```javascript JavaScript theme={"system"} const API_KEY = "API_KEY"; fetch("https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music", { 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/interests?search=Rhythm%20and%20blues%20music', headers=headers) print(r.json()) ``` ```php PHP theme={"system"} "https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer API_KEY" ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ?> ``` ```csharp C# theme={"system"} using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { var client = new HttpClient(); client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY"); var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music"); 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/interests?search=Rhythm%20and%20blues%20music", nil) req.Header.Add("Authorization", "Bearer API_KEY") resp, _ := client.Do(req) 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 GetAdInterests { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music")) .header("Authorization", "Bearer API_KEY") .GET() .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` ```ruby Ruby theme={"system"} require 'net/http' require 'json' uri = URI('https://api.ayrshare.com/api/ads/facebook/interests?search=Rhythm%20and%20blues%20music') req = Net::HTTP::Get.new(uri) req['Authorization'] = 'Bearer API_KEY' res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) } puts res.body ``` ```json 200: Success theme={"system"} { "status": "success", "interests": [ { "id": "6003195554098", "name": "Rhythm and blues music", "topic": "News and entertainment", "audienceSizeLowerBound": 669180255, "audienceSizeUpperBound": 786955980 }, { "id": "6003470511564", "name": "Do it yourself (DIY)", "topic": "Hobbies and activities", "audienceSizeLowerBound": 418387661, // Lower bound of audience size "audienceSizeUpperBound": 492023890 // Upper bound of audience size }, { "id": "6002926036121", "name": "Italy", "topic": "Travel, places and events", "audienceSizeLowerBound": 279313350, // Lower bound of audience size "audienceSizeUpperBound": 328472500 // Upper bound of audience size } ], "count": 3, "lastUpdated": "2025-03-27T01:01:38.547Z", "nextUpdate": "2025-03-27T01:12:38.547Z" } ``` ```json 200: Filtered by special ad category theme={"system"} { "status": "success", "interests": [ { "id": "6003269553527", "name": "Nursing", "audienceSizeLowerBound": 91340120, "audienceSizeUpperBound": 107420310 }, { "id": "6003204427551", "name": "Health care", "audienceSizeLowerBound": 412880440, "audienceSizeUpperBound": 485610770 } ], "count": 2, "specialAdCategories": ["EMPLOYMENT"], "lastUpdated": "2026-09-11T01:01:38.547Z", "nextUpdate": "2026-09-11T01:12:38.547Z" } ``` ```json 400: Ad interests error theme={"system"} { "action": "get ad interests", "status": "error", "code": 368, "message": "Error getting ad interests. Please try again or contact us if the issue persists." } ```