SocialOS | Documentation


Full-text search is supported on message content and metadata, and on
user metadata. User metadata is attached to messages as they are
indexed, so messages are searchable by user metadata as it was at the
time the message was posted (which may of course vary from the live

Compound searches are available through query strings using boolean
algebra – combining subterms with AND, OR, and NOT. The search engine
supports exact matches for terms and phrases, fuzzy matches, wildcards,
and range matches for ordered metadata fields (e.g. the timestamp).

In addition, it supports specialised search modes such as more like
, which attempts to find posts as similar as possible to the text
sample, and fuzzy like this, which performs an equivalent search but
with fuzzy matching on the search terms.

It is possible to combine search terms so as to perform (for example) a
search for a specific term in messages from a particular city, posted
during a given week, and written in a specified language.

Search is available as an on-demand API and as a streaming filter. See
the Filter API for more details on the latter use.

Query Examples

Method Example Result
simple rabbit Finds messages containing the word “rabbit”
rabbi* Finds messages containing words beginning with “rabbi”
rabbi? Finds messages containing words beginning with “rabbi” with one additional letter at the end
rabbit~ Find words similar to “rabbit”
compound rabbit AND carrot Finds messages containing both “rabbit” and “carrot”
rabbit OR bunny Finds messages containing either word
(rabbit OR bunny) AND carrot Finds messages containing either rabbit or bunny, and carrot
rabbit OR bunny AND carrot Finds messages containing either “rabbit”, or both “bunny” and “carrot” (probably not what you intended)
rabbit NOT carrot Finds messages containing “rabbit” but not “carrot”
+rabbit carrot Finds messages containing “rabbit” and optionally carrot
rabbit -carrot Finds messages containing “rabbit” but not “carrot”
fields bio.about:rabbits Finds messages where the user’s bio.about field mentions rabbits
bio.about:(rabbit OR bunny) Finds messages where the user’s bio.about fields mentions rabbits or bunnies Finds messages sent from Australia
bio.\*:rabbit Finds messages where any bio field contains the word “rabbit”
_exists_:bio.religion Finds messages where the bio metadata contains a religion field
_missing_:bio.about Finds messages where there is no bio.about field
bio.about:rabbit AND carrot Finds messages where the bio mentions rabbits and the content mentions carrots
range bio.age:[18 TO 24] Finds messages where the user’s age range is between 18 and 24 (assuming the age is supplied in the bio metadata)
proximity “rabbit carrot”~5 Finds messages where the word “carrot” appears within 5 words of “rabbit”
addressing to:[email protected] Finds messages sent to user
from:[email protected] Finds messages sent by user
cc:[email protected] Finds messages cc’d to user
bcc:[email protected] Finds messages bcc’d to user
attn:[email protected] Finds messages marked to the attention of
dates time:[1340150400 TO 1340236799] Finds messages posted on 2012-06-20 (all system times are GMT)
time:{1340150400 TO 1340236799} Finds messages posted on 2012-06-20 (all system times are GMT) excluding the endpoints

Advanced Search

Advanced search functions are available via the Grab and Engagement APIs.

The Grab API and Grab builder allow the creation of filters based on:

  • Content source (SocialOS, Twitter, Reddit, YouTube, Facebook, and others)
  • Tags, names, keywords and bio
  • Selective exclusion of tags, names, and other terms
  • Links, media content, likes, reposts, and comments
  • Engagement, trending, and highlight scoring
  • Location and language
  • Sentiment analysis
  • Smart filters for low-quality posts, including profanity, spam, and bot detection

The Engagement API supports simple searches with complex functionality. Terms are automatically matched against:

  • Full and partial names
  • Organisation and job title
  • Email address, phone number, web site, and social identities
  • Location (country, state, county, city, street)
  • Bio text and recent social posts

Updated 2 years ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.