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.

Facets

Ad-hoc, saved topic, saved coverage, social theme, and social topic searches can return optional facet results: counts grouped by fields such as media type, sentiment, country, or language. Facets are calculated across all mentions matching the search, not only the current page. Except for the SENTIMENT facet's UNSET bucket, facet buckets are returned only when at least one matching mention has that value. Invalid or unclassified buckets may be omitted, so bucket counts do not always sum to totalResults. Facets let clients build filter controls and summary charts without downloading every mention or running a separate search for each value.

Request one or more facet fields with the top-level facets property. For an ad-hoc or saved topic search:

{
  "query": {
    "publicationDate": {
      "relative": "LAST_7_DAYS"
    },
    "standardQuery": {
      "areas": ["HEADLINE", "LEAD", "BODY"],
      "anyTerms": ["Tesla"]
    }
  },
  "facets": ["MEDIA_TYPE", "SENTIMENT"]
}

For a social theme or social topic search, the identifier and publication date remain top-level:

{
  "name": "My Social Source",
  "publicationDate": {
    "relative": "LAST_7_DAYS"
  },
  "facets": ["MEDIA_TYPE", "SENTIMENT"]
}

The response includes the requested groups alongside the normal search results:

{
  "totalResults": 1240,
  "mentions": [],
  "facets": [
    {
      "field": "MEDIA_TYPE",
      "values": [
        { "value": "ONLINE_NEWS", "count": 900 },
        { "value": "TV", "count": 210 },
        { "value": "RADIO", "count": 130 }
      ]
    },
    {
      "field": "SENTIMENT",
      "values": [
        { "value": "POSITIVE", "count": 500 },
        { "value": "NEUTRAL", "count": 440 },
        { "value": "NEGATIVE", "count": 300 },
        { "value": "UNSET", "count": 0 }
      ]
    }
  ]
}

The supported facet fields are listed in the ad-hoc search API reference.

See Saved Topic Search, Social Theme Search, and Social Topic Search for complete endpoint-specific request examples. The same facet fields and response structure apply.

Saved coverage searches also accept the same fields, plus ARCHIVED_CRITICAL_MENTION, TAG, TAG_GROUP, FOLDER, SAVE_SOURCE_TYPE, and SAVING_SEARCH. Add facets to requests sent to Saved Coverage Search, including folder and tag searches. Saved coverage facet values may be internal IDs encoded as strings; use the saved coverage list endpoints to resolve tag, tag-group, and folder IDs where applicable.

Geography facets (CONTINENT, COUNTRY, PROVINCE, CITY, and COUNTY) return geography IDs encoded as strings, not display names. Resolve them through Lookup Geographies.

The LANGUAGE facet returns only supported two-character ISO 639-1 language codes. Unassigned, blank, unsupported, and non-two-character language buckets are omitted.

The author/outlet reach and AVE facets rank entries that contain a sum by that value. The outlet domain-authority facet ranks entries that contain metricValue by that value. Entries without the relevant metric may follow and should not be treated as ranked. Other facets normally contain only value and count. The facets response property is normally omitted when no facets were requested. A requested facet may contain an empty values array when no matching buckets exist.

When matching results exist, the SENTIMENT facet includes an UNSET bucket for mentions without sentiment. Its count is 0 when every matching mention has sentiment.

Facets summarize the current query. A media-type filter such as query.mediaTypes: ["ONLINE_NEWS"] for ad-hoc and saved topic searches, or filters.mediaTypes: ["ONLINE_NEWS"] for social searches, restricts results. facets: ["MEDIA_TYPE"] requests a breakdown of that already-filtered result set.