Search

Helpers for the Facebook Search (fbsearch/) surface — user search, blended top results, hashtag/place lookups, and typeahead suggestions.

v2 SERP endpoints

The *_v2 methods hit the same fbsearch/<tab>_serp/ endpoints the official Instagram app uses to render the Search → Top / Accounts / Reels tabs. They return raw payloads so callers can drive their own pagination.

Method	Return	Description
`fbsearch_accounts_v2(query: str, page_token: str = None)`	`dict`	"Accounts" tab — `fbsearch/account_serp/`. Pagination via `next_page_token`.
`fbsearch_reels_v2(query: str, reels_max_id: str = None, rank_token: str = None)`	`dict`	"Reels" tab — `fbsearch/reels_serp/`.
`fbsearch_topsearch_v2(query: str, next_max_id: str = None, reels_max_id: str = None, rank_token: str = None)`	`dict`	Default "Top" blended tab — `fbsearch/top_serp/`.
`fbsearch_item(item_id: str, search_surface: str, query: str, ...)`	`dict`	Generic `fbsearch/{item_id}/` tab helper with optional pagination cursors.
`fbsearch_keyword_typeahead(query: str, timezone_offset: int = 0, count: int = 30)`	`dict`	Raw keyword/typeahead suggestions via `fbsearch/keyword_typeahead/`.
`fbsearch_typeahead_stream(query: str, timezone_offset: int = 0, count: int = 30)`	`dict`	Raw streaming typeahead payload via `fbsearch/typeahead_stream/`.
`fbsearch_typehead(query: str)`	`List[dict]`	Typeahead user suggestions, flattened from the `stream_rows` envelope returned by `fbsearch/typeahead_stream/`.
`media_search(query: str, amount: int = 27)`	`List[Media]`	Typed media search from the private Top blended fbsearch SERP, including media-grid cursor pagination.

Example:

# Top tab — first page
top = cl.fbsearch_topsearch_v2("python")

# Accounts — paginate
page1 = cl.fbsearch_accounts_v2("python")
page2 = cl.fbsearch_accounts_v2("python", page_token=page1["next_page_token"])

# Reels — paginate
page1 = cl.fbsearch_reels_v2("python")
page2 = cl.fbsearch_reels_v2("python", reels_max_id=page1["reels_max_id"])

# Typeahead — flat list of user dicts
users = cl.fbsearch_typehead("py")

# Top media — typed Media objects
medias = cl.media_search("python", amount=3)

media_search() raises PrivateError when the response omits media_grid, returns null, or has a malformed grid or sections payload. A valid empty grid still returns []. The exception also propagates on later pages instead of returning partial results. Repeated pagination cursor pairs stop further requests. These checks do not guarantee that Instagram will return search results.

Other search helpers

Method	Return	Description
`search_users(query: str)`	`List[UserShort]`	User search via `users/search/`.
`search_hashtags(query: str)`	`List[Hashtag]`	Hashtag search via `tags/search/`.
`search_music(query: str)`	`List[Track]`	Music/audio search via `music/audio_global_search/`.
`fbsearch_topsearch_flat(query: str)`	`List[dict]`	Legacy flat top-search via `fbsearch/topsearch_flat/`.
`web_search_topsearch(query: str)`	`dict`	Raw web top-search payload via `web/search/topsearch/`.
`web_search_topsearch_hashtags(query: str)`	`List[Hashtag]`	Extract hashtags from the web top-search payload.
`fbsearch_suggested_profiles(user_id: str)`	`List[UserShort]`	Suggested profiles via `fbsearch/accounts_recs/`.
`fbsearch_recent()`	`List[Tuple[int, ...]]`	Recently searched items.

For places, see Location.