Facebook Search API: Find Public Ads by Keyword in One Call

Send a keyword to the Facebook search API at POST https://api.desearch.ai/desearch/facebook/search and you get back normalized public Meta Ad Library records as JSON, in one synchronous call. It searches ads, not organic Facebook posts.

This guide covers what the endpoint searches, how to make your first request, what a real response looks like, and how to page and chain calls. For the product overview, see the Facebook API page.

What this Facebook search API searches (and what it does not)

Public Ad Library records by keyword, phrase or hashtag

The query field takes a Meta Ad Library keyword, phrase or hashtag. The endpoint returns the public ad records that match, with fields such as the ad text, headline, call to action, landing URL, whether the ad is active, and the platforms it runs on.

That makes it useful when you want to see which ads run around a topic, how advertisers word their offers, or where an ad sends people.

Not exposed: organic post keyword search, private surfaces, messaging, publishing

The API reference is explicit about the limits: "Organic Facebook post keyword search, private/account-authenticated surfaces, messaging, and publishing are intentionally not exposed."

So you can't use this endpoint to search regular posts by keyword, read anything behind a login, send messages, or post. It only covers public Ad Library records.

Make your first request

Get an API key in Console

Create a key in Desearch Console. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.

Request parameters

cURL example

This is the exact request we ran for the sample later in this post:

curl -X POST https://api.desearch.ai/desearch/facebook/search \
  -H "Authorization: $DESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI search"}'

We didn't send count, so the default of 10 applied, and 10 results came back.

Python example

This version is written from the API schema with plain requests. It is not a captured run:

import os
import requests

resp = requests.post(
    "https://api.desearch.ai/desearch/facebook/search",
    headers={"Authorization": os.environ["DESEARCH_API_KEY"]},
    json={"query": "AI search"},
)
resp.raise_for_status()

ads = resp.json()
for ad in ads:
    print(ad.get("id"), ad.get("cta"), ad.get("headline"))

print(resp.headers.get("x-desearch-next-cursor"))

Use .get() for every field. Some fields, such as headline, only appear on some ads.

What a real search returns

We ran the cURL request above once, on 2026-10-24. It returned 10 results with a 200 status in about 3.5 seconds. That's what we saw on one run, not a speed promise.

The response is a JSON array of ads. Here is one item from that run:

{
  "id": "28336218789297675",
  "url": "https://www.facebook.com/ads/library?id=28336218789297675",
  "text": "[ad text trimmed]",
  "createTime": 1784790000,
  "endDate": "2026-10-24T07:00:00.000Z",
  "author": {
    "id": "143609916516",
    "name": "[advertiser]",
    "category": "Website"
  },
  "stats": {},
  "media": [],
  "hashtags": [],
  "cta": "See details",
  "headline": "Chat with us",
  "linkDescription": "[trimmed]",
  "active": true,
  "platforms": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER"]
}

Trimmed from a real response. Ad copy and advertiser name removed.

Read the response fields

Ad fields

These fields describe the ad itself:

• headline: the ad's headline, when it has one.
• cta: the call to action shown on the button.
• linkUrl: in the reference's words, "Ad landing URL from snapshot.link_url. url stays the Ad Library or post URL." Use it to see where an ad sends people. These are often long tracking URLs, so store them as they come.
• linkDescription: the short text under the headline, when present.
• active: whether the ad is running.
• endDate: when the ad stops or stopped running.
• platforms: the publisher platforms, "such as FACEBOOK or INSTAGRAM".

Shared fields

These general fields can be empty or missing on any item:

• id and url: the Ad Library ID and its page.
• text: the ad copy.
• createTime: a Unix timestamp.
• author: the advertiser's page, with id, name and category.
• stats, media, hashtags: engagement, media and tags, when the source has them.

Don't count on every field being filled. In our sample, stats was {} and media was [] on every item we checked, and headline and linkDescription showed up on some ads only. Read fields with defaults and skip what's missing.

Page through results with a cursor

The token for the next page comes back in the x-desearch-next-cursor response header. The reference describes it as "Present only when there is a next page; absent on the last page."

To get the next page, send that value back unchanged as cursor, on the same route and with the same query. A cursor is valid for 24 hours. Any other value, including an expired cursor, "returns 422 and is not charged."

This loop is written from the API schema, not a captured run. It keeps asking for pages until the header is gone:

import os
import requests

url = "https://api.desearch.ai/desearch/facebook/search"
headers = {"Authorization": os.environ["DESEARCH_API_KEY"]}
body = {"query": "AI search"}

ads = []
while True:
    resp = requests.post(url, headers=headers, json=body)
    resp.raise_for_status()
    ads.extend(resp.json())

    cursor = resp.headers.get("x-desearch-next-cursor")
    if not cursor:
        break
    body = {"query": "AI search", "cursor": cursor}

print(len(ads))

Go further: post, page, page posts, comments and hashtags

Once you have a post or page ID, these endpoints let you look closer:

• GET https://api.desearch.ai/desearch/facebook/post/{id}: a single post.
• GET https://api.desearch.ai/desearch/facebook/profile/{profile_id}: a page.
• GET https://api.desearch.ai/desearch/facebook/profile/{profile_id}/posts: posts from a page.
• GET https://api.desearch.ai/desearch/facebook/comments/{post_id}: comments on a post. Upstream returns at most about 10 comments per page, whatever count you send.
• GET https://api.desearch.ai/desearch/facebook/hashtag/{tag}: public Ad Library records for a hashtag (not organic hashtag search).

If you want to watch a set of advertisers over time, see how to track ads in the Facebook Ad Library with Python. This post stays at the raw API level.

See what each call cost

Billable responses carry four headers:

• X-Desearch-Cost-Usd
• X-Desearch-Usage-Count
• X-Desearch-Service
• X-Desearch-Currency

Search returns a JSON array, so the cost lives in these headers only, not in the body. Our sample showed x-desearch-usage-count: 10 for 10 results.

For how usage turns into billing, read pricing and billing, and see current rates on the pricing page.

Other public social sources

• To work with Instagram, see how to search Instagram hashtags with an API.
• For X, here's how to search hashtags on X.
• To plan posting times, see the best time to post on TikTok, Instagram and Facebook.

AI Search covers web and X only; Facebook has its own endpoints.

FAQ

Is there an API to search Facebook by keyword?

Yes, for public Meta Ad Library records, via POST https://api.desearch.ai/desearch/facebook/search. Organic post keyword search is not exposed.

How many results per request?

Up to 100. Set count from 1 to 100; the default is 10, and the provider page may be smaller.

How do I get the next page?

Send the x-desearch-next-cursor header value back as cursor within 24 hours. An invalid or expired cursor returns 422 and is not charged.

Can I get the landing page and CTA of an ad?

Yes. Read linkUrl, cta and headline.

Can I read comments on a Facebook post?

Yes, with GET https://api.desearch.ai/desearch/facebook/comments/{post_id}. Upstream returns at most about 10 comments per page; use the cursor for more.

Does AI Search cover Facebook?

No. AI Search covers web and X; Facebook has its own endpoints.

How do I see what a call cost?

Read the X-Desearch-Cost-Usd response header. Prices are on the pricing page.

Get started

Get an API key in Console and run your first Facebook ad search. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.

Open Console

Reference: Facebook search API reference