Search Instagram posts with boolean operators

Search public Instagram posts by keyword or boolean query. Unlike the relevance-only Search endpoint, this accepts boolean operators, making it suited to precise social-listening queries.

GET /v1/instagram/search/boolean

Boolean operators supported

Combine terms with AND / OR and wrap exact phrases in double quotes, e.g. "nike" AND "running shoes" OR "marathon". Results are relevance-ranked and deduplicated.

Query parameters

Parameter	Type	Default	Description
query	string	—	Required. A keyword or boolean query, e.g. "nike" AND "running shoes" OR "marathon".
max_pages	integer	1	Number of result pages to fetch. Maximum 50.

Pagination: one page ≈ 20 posts. Fetching max_pages pages returns those pages' posts, deduplicated across pages, in relevance order. Fewer pages may come back when results run out.

Examples

Boolean query:

curl -G "$LISTENX_BASE/v1/instagram/search/boolean" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query="nike" AND "running shoes" OR "marathon"'

Keyword query, three pages:

curl -G "$LISTENX_BASE/v1/instagram/search/boolean" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=electric vehicles OR EV' \
  --data-urlencode 'max_pages=3'

Response

{
  "query": "\"nike\" AND \"running shoes\" OR \"marathon\"",
  "pages_requested": 3,
  "pages_fetched": 3,
  "returned": 48,
  "results": [
    {
      "shortcode": "DI1OLYNtCKQ",
      "url": "https://www.instagram.com/p/DI1OLYNtCKQ/",
      "type": "post",
      "username": "someaccount",
      "title": "…",
      "snippet": "…",
      "thumbnail_url": "https://…"
    }
  ],
  "billing": {
    "endpoint": "instagram.boolean_search",
    "units": 3,
    "unit_price": "0.010000",
    "amount": "0.030000",
    "balance_after": "97.240000",
    "request_id": "…"
  }
}

Fields

Field	Description
query	The query exactly as submitted.
pages_requested	The max_pages you asked for.
pages_fetched	Pages actually fetched (also the number of billed units).
returned	Number of posts in results (deduplicated across pages).
results[]	Post records — shortcode, url, type, username, title, snippet, thumbnail_url.

Billing

Billed per page fetched — units = pages_fetched, minimum 1. So max_pages=3 costs up to 3 units (fewer if results run out sooner). See Billing.

Notes

• This endpoint returns lightweight discovery records. To fetch complete details (all engagement metrics, media URLs, tagged users, music, etc.) for a result, call the post endpoint with its shortcode.
• Use Search instead when you want hashtag or simple relevance queries with engagement metrics inline.