Search posts

Search public Facebook posts by keyword. Results are relevance-ranked and deduplicated.

GET /v1/facebook/search

Query parameters

Parameter	Required	Description
query	yes	Keyword or phrase, e.g. electric vehicles or "climate summit".
max_pages	no	Number of result pages to fetch (1–50, default 1). Each page returns ~10 posts. Billed per page fetched.

Example

curl "$LISTENX_BASE/v1/facebook/search?query=electric%20vehicles&max_pages=2" \
  -H "X-API-Key: $LISTENX_KEY"

Response

{
  "query": "electric vehicles",
  "pages_requested": 2,
  "pages_fetched": 2,
  "returned": 19,
  "next_cursor": "eyJ...",
  "results": [
    {
      "id": "100071000_555000111",
      "url": "https://www.facebook.com/story.php?story_fbid=555000111&id=100071000",
      "author": {
        "id": null,
        "name": "CleanTech Daily",
        "username": "CleanTechDaily",
        "url": "https://www.facebook.com/CleanTechDaily/"
      },
      "text": "Global electric vehicles sales crossed a record this quarter…",
      "created_at": "3 hrs"
    }
  ],
  "billing": {
    "endpoint": "facebook.search",
    "units": 2,
    "unit_price": "0.010000",
    "amount": "0.020000",
    "balance_after": "97.230000",
    "request_id": "…"
  }
}

Fields

Field	Description
id	Post id — pass to the post endpoint.
url	Canonical post permalink.
author	Post author (id, name, username, url).
text	Post text, when present.
created_at	When the post was published, as shown by Facebook.
next_cursor	Pass as cursor on a follow-up request to continue; null when exhausted.

Billing

Billed per page fetched — units equals pages_fetched. See Billing.

Errors

HTTP	code	Meaning
429	upstream_rate_limited	Transient block — retry with backoff.