Search Usage

Every search request — ad-hoc or saved topic — takes a query object with exactly one of two mutually exclusive modes: Standard or Expert. This page covers the rules for each and gives worked examples.

note

Submit exactly one of standardQuery or expertQuery per request. Submitting both, or neither, is rejected with a validation error.

Standard vs. Expert

	Standard	Expert
Shape	Three separate lists: anyTerms, mustAllTerms, mustNotTerms	A single free-text boolean expression string (search)
Syntax	None — each list entry is a literal phrase, matched as-is	Full boolean grammar: AND, OR, AND NOT, quoting, wildcards, proximity, grouping
Best for	Simple "any of these OR all of these, but NOT these" searches without writing boolean syntax	Precise or nested logic that doesn't reduce cleanly to three flat lists

Both modes require an areas field — see Areas below.

Standard Search

standardQuery accepts three optional lists of plain-text terms, which are combined as:

(anyTerms[0] OR anyTerms[1] OR ...)
AND (mustAllTerms[0] AND mustAllTerms[1] AND ...)
AND NOT (mustNotTerms[0] OR mustNotTerms[1] OR ...)

• anyTerms — matches if any of these terms are present (an OR group).
• mustAllTerms — matches only if all of these terms are present (an AND group).
• mustNotTerms — excludes mentions containing any of these terms.
• At least one of anyTerms or mustAllTerms must be non-empty — mustNotTerms alone is not a valid search.
• Each entry is a literal phrase (multi-word entries are matched as a phrase, not tokenized) — there is no boolean, wildcard, or proximity syntax in Standard mode. If you need */? wildcards, proximity (~N), or nested grouping, use Expert mode instead.

Example

"standardQuery": {
  "areas": ["HEADLINE", "BODY", "LEAD"],
  "anyTerms": ["Coca-Cola", "Pepsi"],
  "mustAllTerms": ["355ml"],
  "mustNotTerms": ["RC Cola"]
}

This matches mentions of ("Coca-Cola" or "Pepsi") that also mention "355ml", excluding any that mention "RC Cola" — equivalent to the Expert query (Coca-Cola OR Pepsi) AND (355ml) AND NOT ("RC Cola").

Expert Search

expertQuery.search is a single boolean expression string, following the Agility Expert Search format. It's more powerful than Standard search but has hard formatting rules — violating any of them returns a validation error.

:::note For LLMs and MCP clients The MCP search tool builds its search field using this same Expert Search syntax. Follow the rules and query strategy below when constructing that field. :::

Rules

• Join terms with AND, OR, or AND NOT. Operators must be fully uppercase (and/or/not are rejected) and must sit between two terms — never adjacent to each other or to nothing (e.g. a trailing AND OR is invalid).
• Wrap multi-word terms in double quotes: "Calgary Flames". A bare word is a single term.
• Balance every parenthesis, and use them to group logic: ("Calgary Flames" OR Oilers) AND NOT hockey.
• Standalone (unquoted) words support wildcards — ? for a single character, * as a trailing wildcard: invest* matches investment, investor, investing. Quoted phrases may not contain wildcards — list variants instead: "joint venture" OR "joint ventures".
• Proximity: append ~N to a quoted phrase to match its words within N positions of each other: "Prime Minister Trudeau"~3 matches "Prime Minister Justin Trudeau". For an n-word phrase, use at least ~(n-1); use a larger number to allow for more inserted words.
• An expression may not begin with AND, OR, or AND NOT.
• Expressions must be under 3072 characters.
• Don't put outlet names, journalist/contact names, or URLs in the query — use the dedicated outletNames / contactNames filters for those instead.

Example

"expertQuery": {
  "areas": ["HEADLINE", "BODY", "LEAD"],
  "search": "(355ml) AND (Coca-Cola OR Pepsi) AND NOT (\"RC Cola\")"
}

Query strategy: start simple, broaden with OR, narrow with AND

• Default to the simplest expression that could plausibly work. Each AND you add sharply reduces matches — over-constraining with multiple ANDs is the most common cause of missing relevant coverage.
• For a single entity (a brand, person, or event), one term or one OR group is usually enough — no AND needed.
• Group synonyms with OR; reach for AND only when the search genuinely needs multiple distinct concepts in the same mention. Use AND NOT to remove recurring false positives.
• Avoid redundancy: a standalone word already matches any phrase containing it (Tesla already covers "Tesla Motors"), and a wildcard already covers its inflections (invest* makes investment OR investor redundant).
• Disambiguate a broad/ambiguous term with AND rather than piling on OR variants — prefer Apple AND (iPhone OR Mac OR iOS) over Apple OR "Apple Inc".

More examples

Intent	Expert query
Tesla news	Tesla
Tesla recalls	Tesla AND (recall* OR "safety issue" OR defect*)
Apple product launches, excluding financial news	Apple AND (launch* OR release* OR unveil* OR announc*) AND NOT (stock OR shares OR earnings OR "quarterly results")
Renewable energy investment	("renewable energy" OR "clean energy" OR solar OR wind) AND (invest* OR fund* OR financ* OR capital)

Common errors

Cause	Error
Operator in lowercase, or otherwise malformed	Invalid operator. Operators (AND, OR, NOT) must be fully uppercase
Unmatched (	Opening parenthesis without a matching closing parenthesis
Unmatched )	Closing parenthesis without a matching opening parenthesis
Unclosed "	Quoted phrase is missing a closing quote
Operator with no following term (e.g. expression ends in AND)	Expected a search term but found end of expression
Query starts with AND/OR/AND NOT, or an operator appears where a term is expected	Unexpected token: '...' near '...'
A term is both required and excluded, e.g. apple AND NOT apple	Contradictory boolean expression logic with the term: 'apple'

Areas

Both Standard and Expert queries take an areas field controlling which parts of a mention the query must match against, combined as OR:

• HEADLINE — the mention's headline/title.
• LEAD — the opening of the body (lede).
• BODY — the full body text. BODY already includes LEAD, so combining the two is redundant.
• Use HEADLINE + LEAD when the topic needs to be prominent in the mention; use HEADLINE alone when the topic must be the mention's actual subject, not just mentioned in passing.

Related filters

Some intent is better expressed as a dedicated filter than as query text:

• Outlet names and contact/journalist names — use outletNames / contactNames, not the query string.
• Media type (news, broadcast, social, etc.), sentiment, and date range — use the corresponding top-level filters rather than trying to encode them in the query.

See the ad-hoc search reference for the full request schema.