SocialHz Engineering · 31 October 2026 · Requested by a customer

Multi-term search: one query, a search per term

GET /api/v1/search?platform=instagram

What shipped

On Instagram, a query with several terms is split, each term is searched on its own, and the posts are merged into one answer. Every post says which terms found it.

Why

A team tracking many brands every week ran one search per brand and merged the results in a spreadsheet. Sending the brands as one OR query didn't work either. We tested it: the busier term filled the page and the quieter one disappeared. That's why each term now gets its own search.

How the query is split

• It splits on or as a word on its own (any case), on | and on a comma. Brightleaf or Northwind, Lumina is 3 terms.
• Text in double quotes is never split: "Rock or Roll Studio" is 1 term, sent with its quotes.
• Up to 25 terms, each at least 2 characters.

GET /api/v1/search?platform=instagram
    &query=Brightleaf or Northwind or "Blue Harbor Gin"&pages=2

What comes back

• Posts are interleaved, one from each term in turn, so no term crowds out another. A post two terms found appears once, with both in matched_terms.
• terms[].posts always agrees with matched_terms: a post two terms found counts for both.
• pages is the pages fetched per term. page above 1 is refused, and page_size is ignored and listed in filters.ignored.
• next_cursor carries on every term that has more, and retries any term that failed.

"posts": [{ "id": "…", "matched_terms": ["Brightleaf", "Northwind"], … }],
"terms": [
  { "term": "Brightleaf", "posts": 28, "pages": 2, "has_more": true },
  { "term": "Northwind",  "posts": 11, "pages": 2, "has_more": false },
  { "term": "Blue Harbor Gin", "posts": 0, "pages": 0, "has_more": true,
    "error": "The platform could not be searched just now. Nothing was charged. Try again in a moment." }
]

Credits

Each term is its own charge in the credit ledger, at the page price. A term that fails, or isn't reached in time, is refunded.

Switched on per workspace. Ask us and we'll turn it on for yours.

Request a feature

Tell us what you need on the updates page. The engineering team reads every request.

Search API reference · All engineering updates