<!-- The markdown copy of https://oppalerts.com/docs/mcp/news_search . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / news_search

# news_search

`POST https://mcp.oppalerts.com/mcp tool: news_search`

Search the News Index, a permanent collection of news pages, podcasts, and videos: by semantic similarity, by words in titles and bodies, or both, with date, document type, rank, outbound link, and type score filters.

## What it does

The News Index is a collection of news pages, podcasts, and videos that keeps every document. The tool searches it by semantic similarity, by words, or by both.

- By semantic similarity: set `similarity_target`, for example to `similarity_text` with a `similarity_text`. Each result then has a `similarity_score` from 0 to 100.
- By words: send `title_query`, `body_query`, or both. With both, `title_body_join` says how they join.
- Filters: dates, document type, host and domain rank, outbound links, and type scores.
- By type: send `type_scores`, with an opportunity type or a content type and its `type_score_min`. Each result then has `type_scores`, with its score for each type you send. `sort` `type_score` puts the highest score of one type first.

The call works with or without a campaign. With a campaign, a result whose site is an organization of the campaign has an `org` key. The answer has `total_matches` (the matches) and `returned` (the results in this answer).

All `news_` and `prospects_` tools of one account share one daily count of index searches. Only one index search runs at a time. [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows the searches that are left today.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

The tool has 43 parameters, with each part of an object counted one by one. Send them as the `arguments` of the tool call.

**`campaign`int, optional, 1 to 4294967295**

Optional. The campaign id, a whole number from 1 to 4294967295, from `campaigns_list`. When you send it, the campaign must be in this account, and a result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. When you do not send it, no result has an org key. `similarity_target` campaign and `saved_opportunity` need a campaign.

**`similarity_target`none | campaign | similarity_text | saved_opportunity, required**

Required. The vector: what the pages must be semantically similar to. `none`: no vector, and the other fields alone find the pages. `campaign`: the market description of the campaign. `similarity_text`: the text in `similarity_text`. `saved_opportunity`: the similarity text of the saved opportunity in `similarity_target_opportunity`. A target that has no text yet is refused. With a vector, each result has a `similarity_score` from 0 to 100.

**`similarity_target_opportunity`int, required in some cases, 1 to 4294967295**

Required when `similarity_target` is `saved_opportunity`, and refused with any other `similarity_target`. The id of a saved opportunity of the campaign, a whole number from 1 to 4294967295, from `campaigns_saved_opportunities`. The saved opportunity must have a similarity text. An id that is not in the campaign answers HTTP 404, `opportunity_not_found`.

**`similarity_text`string, required in some cases, at most 20000 characters**

Required when `similarity_target` is `similarity_text`, and refused with any other `similarity_target`. The text the pages must be semantically similar to, at most 20,000 characters. A text of only spaces is refused.

**`similarity_score_min`int, optional, 1 to 100**

Optional, and refused when `similarity_target` is `none`. The least `similarity_score` a result must have, a whole number from 1 to 100. Not sent: no minimum.

**`title_query`string, optional, at most 500 characters**

Optional. Words the title must have, at most 500 characters. It takes these search operators: AND, OR, MAYBE, NEAR/N, and NOTNEAR/N in capitals, the Negation operator (-), the Phrase search operator, the Proximity search operator (~N), the Exact form modifier (=), the IDF boost modifier (^N), the Wildcard operator (* at the end of a word), and Grouping with parentheses (one level). A wrong use is refused with a sentence that names the field. The full list is in [Advanced Search Operators](https://oppalerts.com/docs/the-data/advanced-search-operators). At most 20 words or phrases: a text with more is refused, and nothing is cut. A text with no word or phrase, such as only OR or only spaces, is refused. Not sent: no title words.

**`body_query`string, optional, at most 500 characters**

Optional. Words the body must have, at most 500 characters, with the same rules as `title_query`. Not sent: no body words.

**`title_body_join`and | or, required in some cases**

Required when you send both `title_query` and `body_query`, and refused when you send one of them or none. `and`: a page must match both. `or`: a page must match one of them.

**`published_from`string, optional, at most 10 characters**

Optional. The first published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused: a text in another form, and a `published_from` after `published_to`. Not sent: no first day.

**`published_to`string, optional, at most 10 characters**

Optional. The last published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Not sent: no last day.

**`indexed_from`string, optional, at most 10 characters**

Optional. The first day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused: a text in another form, and an `indexed_from` after `indexed_to`. Not sent: no first day.

**`indexed_to`string, optional, at most 10 characters**

Optional. The last day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Not sent: no last day.

**`document_type`page | podcast | video, optional**

Optional. The document type to search: page, podcast, or video. Not sent: all 3.

**`pr_domain_min`int, optional, 0 to 100**

Optional. Keep the pages whose domain PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above `pr_domain_max`.

**`pr_domain_max`int, optional, 1 to 100**

Optional. Keep the pages whose domain PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no domain PageRank stays in the results. 0 is refused. Not sent: no maximum.

**`pr_host_min`int, optional, 0 to 100**

Optional. Keep the pages whose host PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above `pr_host_max`.

**`pr_host_max`int, optional, 1 to 100**

Optional. Keep the pages whose host PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no host PageRank stays in the results. 0 is refused. Not sent: no maximum.

**`prot_domain_min`int, optional, 0 to 1000000**

Optional. Keep the pages whose domain PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 applies no minimum. Not sent: no minimum. Refused when it is above `prot_domain_max`.

**`prot_domain_max`int, optional, 1 to 1000000**

Optional. Keep the pages whose domain PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 is refused. Not sent: no maximum.

**`prot_host_min`int, optional, 0 to 1000000**

Optional. Keep the pages whose host PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 applies no minimum. Not sent: no minimum. Refused when it is above `prot_host_max`.

**`prot_host_max`int, optional, 1 to 1000000**

Optional. Keep the pages whose host PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 is refused. Not sent: no maximum.

**`link_counts_min`object, optional**

Optional. The least number of outbound links of each link type in each page section: {"article"|"nav"|"comments": {"follow"|"nofollow"|"sponsored"|"ugc": n}}. A result must have at least n links of that type in that section. Send only the sections and the link types that you want. Not sent: no minimum.

**`link_counts_min.article`object, optional**

Optional. The article section of the page.

**`link_counts_min.article.follow`int, optional, 0 to 4294967295**

Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.article.nofollow`int, optional, 0 to 4294967295**

Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.article.sponsored`int, optional, 0 to 4294967295**

Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.article.ugc`int, optional, 0 to 4294967295**

Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.nav`object, optional**

Optional. The navigation section of the page.

**`link_counts_min.nav.follow`int, optional, 0 to 4294967295**

Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.nav.nofollow`int, optional, 0 to 4294967295**

Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.nav.sponsored`int, optional, 0 to 4294967295**

Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.nav.ugc`int, optional, 0 to 4294967295**

Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.comments`object, optional**

Optional. The comments section of the page, where visitors add content.

**`link_counts_min.comments.follow`int, optional, 0 to 4294967295**

Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.comments.nofollow`int, optional, 0 to 4294967295**

Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.comments.sponsored`int, optional, 0 to 4294967295**

Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.

**`link_counts_min.comments.ugc`int, optional, 0 to 4294967295**

Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.

**`type_scores`list of objects, optional, 1 to 20 items**

Optional. The types a result must score on, 1 to 20 items. Each item is an object with an `opportunity_type` or a `content_type`, and its `type_score_min`. A result must pass every item. A type named 2 times is refused. Not sent: no type filter. When you send `type_scores`, each result has the key `type_scores`, with the score of the result for each type that you sent. `sort` `type_score` takes exactly 1 item.

**`type_scores[].opportunity_type`string, optional**

An opportunity type as <group>/<type>, for example advertising/newsletter-ads, from `types_opportunity_types`. An item has an `opportunity_type` or a `content_type`, not both. A type that does not exist is refused.

**`type_scores[].content_type`string, optional**

A content type, for example blogs, from `types_content_types`. An item has a `content_type` or an `opportunity_type`, not both. A type that does not exist is refused.

**`type_scores[].type_score_min`int, required, 1 to 100**

Required. The least type score the page must have for this type, a whole number from 1 to 100. 0 is refused.

**`sort`best | similarity | relevance | published | indexed | pr_domain | prot_domain | pr_host | prot_host | type_score, required**

Required. The order of the results. `best`: the strongest word match first, then the nearest in semantic similarity. `similarity`: the nearest in semantic similarity first; refused when `similarity_target` is `none`. `relevance`: the strongest word match first; refused with no `title_query` and no `body_query`. `indexed`: the newest day added to the index first. `published`: the newest published day first. `pr_domain`, `prot_domain`, `pr_host`, `prot_host`: the highest value first. `type_score`: the highest score of the type in `type_scores` first; `type_scores` must hold exactly 1 item, so `sort` `type_score` is refused with no `type_scores` and with 2 or more items.

**`results_limit`int, optional, 1 to 1000, not sent: 100**

Optional. The maximum number of results to return, a whole number from 1 to 1000. Not sent: 100. A number above the maximum of your plan is refused, and the error gives that maximum.

### Rules

- `similarity_target` is required: send `none` for no vector.
- `similarity_text` is required with `similarity_target` `similarity_text`, and `similarity_target_opportunity` with `saved_opportunity`; each one is refused with another `similarity_target`.
- `similarity_score_min` and `sort` `similarity` are refused with `similarity_target` `none`.
- `title_body_join` is required when you send both `title_query` and `body_query`, and refused otherwise.
- `sort` `relevance` is refused with no `title_query` and no `body_query`.
- `sort` `type_score` is refused when `type_scores` does not hold exactly 1 item.
- A call with `similarity_target` `none`, no `title_query`, and no `body_query` is refused.
- A from date after its to date is refused, and so is a minimum above its maximum.
- `partial` is true when more than 15,000 pages match a search with a vector: `results` then comes from only part of the matches.
- When `partial` is true, make the search more specific: use more exact words, a higher minimum PR, a higher minimum type score, or a shorter date range.
- `returned` is the number of results in this answer.
- When you send `type_scores`, each result has `type_scores`, with its score for each of those types.
- The conditions of a search are its date, `document_type`, PR, PRoT, `link_counts_min`, and `type_scores` fields.
- With `similarity_target` `none`, `total_matches` is the number of pages that match the words and the conditions.
- With a vector, `total_matches` is never more than 10,000, and 10,000 means 10,000 or more.
- With a vector together with words or a condition, and `partial` false, `total_matches` is the number of pages that match and have a `similarity_score` of `similarity_score_min` or more, or 10,000 when there are more.
- When `partial` is true, `total_matches` is 10,000.
- With a vector and no words and no condition, the search compares all pages, `partial` is false, and `total_matches` is 10,000.
- In these last 2 cases, `total_matches` is less than 10,000 only when the search found fewer pages with a `similarity_score` of `similarity_score_min` or more: it is then the number of pages found.
- With `sort` `type_score`, the search does not count the matches, and `total_matches` is 0.
- No field has a default value, except `results_limit`: 100 when you do not send it.
- A field that you do not send applies no condition.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "news_search",
    "arguments": {
      "campaign": 3,
      "similarity_target": "similarity_text",
      "similarity_text": "Boutique hotels winning direct bookings from younger travelers in mid-size US cities.",
      "similarity_score_min": 25,
      "title_query": "hotel",
      "published_from": "2026-11-01",
      "published_to": "2026-11-07",
      "sort": "best",
      "results_limit": 10
    }
  }
}
```

### Response

The full sample answer.

```json
{
  "total_matches": 1240,
  "returned": 100,
  "partial": false,
  "results": [
    {
      "id": "1152921504611003120",
      "url": "https://cityguide-example.org/advertise/media-kit",
      "host": "cityguide-example.org",
      "document_type": "page",
      "published_at": "2026-05-10T00:00:00Z",
      "indexed_at": "2026-08-17T21:00:00Z",
      "pr_host": 39,
      "prot_host": 678,
      "pr_domain": 61,
      "prot_domain": 861,
      "similarity_score": 46.8,
      "relevance_weight": 1247.0,
      "org": {
        "relationship": "org_publisher"
      },
      "page": {
        "title": "Advertise with City Guide: media kit",
        "snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
        "link_counts": {
          "article": {
            "follow": 12,
            "nofollow": 3,
            "sponsored": 2,
            "ugc": 0
          },
          "nav": {
            "follow": 34,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          },
          "comments": {
            "follow": 0,
            "nofollow": 0,
            "sponsored": 0,
            "ugc": 0
          }
        },
        "meta": {
          "favicon": "https://cityguide-example.org/favicon-32.png",
          "feeds": [
            "https://cityguide-example.org/feed"
          ],
          "contact": [
            "https://cityguide-example.org/contact"
          ]
        },
        "sections": {
          "article": {
            "links": [
              {
                "url": "https://grand-resorts.example/awards",
                "text": "Grand Resorts",
                "title": "",
                "rel": [
                  "nofollow"
                ],
                "org": {
                  "relationship": "org_competitor"
                }
              }
            ],
            "emails": [
              "press@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0100"
            ],
            "service_accounts": [
              {
                "service": "linkedin",
                "username": "cityguide",
                "label": "City Guide",
                "url": "https://linkedin.com/company/cityguide"
              }
            ]
          },
          "nav": {
            "links": [
              {
                "url": "https://partner-example.com/",
                "text": "Our partner",
                "title": "Partner",
                "rel": [
                  "sponsored"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "hello@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0101"
            ],
            "service_accounts": [
              {
                "service": "twitter",
                "username": "cityguide",
                "label": "",
                "url": "https://x.com/cityguide"
              }
            ]
          },
          "comments": {
            "links": [
              {
                "url": "https://reader-blog-example.net/trip-notes",
                "text": "my trip notes",
                "title": "",
                "rel": [
                  "ugc"
                ],
                "org": {
                  "relationship": "org_partner"
                }
              }
            ],
            "emails": [
              "comments@cityguide-example.org"
            ],
            "phones": [
              "+1 555 0102"
            ],
            "service_accounts": [
              {
                "service": "reddit",
                "username": "cityguide",
                "label": "",
                "url": "https://reddit.com/u/cityguide"
              }
            ]
          }
        }
      }
    }
  ],
  "contacts": {
    "accounts": {
      "head": {
        "facebook": [
          {
            "username": "cityguide",
            "url": "https://www.facebook.com/cityguide",
            "type": "page",
            "count": 14,
            "nsfw": false
          }
        ],
        "x": [
          {
            "username": "cityguide",
            "url": "https://x.com/cityguide",
            "type": "user",
            "count": 21,
            "nsfw": false
          },
          {
            "username": "cityguidedeals",
            "url": "https://x.com/cityguidedeals",
            "type": "user",
            "count": 3,
            "nsfw": false
          }
        ]
      },
      "nav": {
        "instagram": [
          {
            "username": "cityguide",
            "url": "https://www.instagram.com/cityguide",
            "type": "user",
            "count": 18,
            "nsfw": false
          }
        ],
        "x": [
          {
            "username": "cityguide",
            "url": "https://x.com/cityguide",
            "type": "user",
            "count": 17,
            "nsfw": false
          }
        ]
      },
      "article": {
        "linkedin": [
          {
            "username": "grand-resorts",
            "url": "https://www.linkedin.com/company/grand-resorts",
            "type": "page",
            "count": 6,
            "nsfw": false
          }
        ],
        "youtube": [
          {
            "username": "boutiquestays",
            "url": "https://www.youtube.com/@boutiquestays",
            "type": "channel",
            "count": 4,
            "nsfw": false
          }
        ]
      },
      "comments": {
        "onlyfans": [
          {
            "username": "examplecreator",
            "url": "https://onlyfans.com/examplecreator",
            "type": "user",
            "count": 1,
            "nsfw": true
          }
        ],
        "reddit": [
          {
            "username": "tripnotes",
            "url": "https://www.reddit.com/user/tripnotes",
            "type": "user",
            "count": 2,
            "nsfw": false
          }
        ]
      }
    },
    "emails": [
      {
        "email": "press@cityguide-example.org",
        "count": 9
      },
      {
        "email": "hello@cityguide-example.org",
        "count": 4
      }
    ],
    "phones": [
      {
        "phone": "+1 555 0100",
        "count": 7
      },
      {
        "phone": "+1 555 0101",
        "count": 2
      }
    ]
  }
}
```

## Errors

The tool is strict. It checks each call before it runs the search:

- An unknown field is refused, and the error names the field.
- A bad value is refused, and the error names the field: the wrong type, a value out of its range, a value that is not in its list of values, or an empty text, list, or object. To send no value, leave the field out.
- A `title_query` or `body_query` with no word or phrase, such as only OR or only spaces, is refused.
- A `title_query` or `body_query` with a formatting error, a character that is not allowed ([How to Search the Indexes](https://oppalerts.com/docs/the-data/how-to-search-the-indexes)) or a wrong use of one of the [search operators](https://oppalerts.com/docs/the-data/advanced-search-operators), is refused with a sentence that names the field and the error. The query is not searched.
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

An error returns as a tool result with `isError` true. Its text starts with the error code. An example: a call that sends `days`, a field that this tool does not have.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "bad_param: days is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
      }
    ],
    "isError": true
  }
}
```

- `bad_param` (HTTP 400 in the API): a field is unknown, missing, empty, of the wrong type, out of its range, or not one of its values, or the call breaks a rule above. A `results_limit` above the maximum of your plan is refused too.
- `no_campaign` (HTTP 404 in the API): the campaign is not a campaign of your account.
- `opportunity_not_found` (HTTP 404 in the API): the saved opportunity is not in the campaign.
- `search_stopped` (HTTP 422 in the API): the search took more than 10 seconds and was stopped. The message says how to make the search more specific. A stopped search counts as 1 search.
- `one_at_a_time` (HTTP 429 in the API): another index search of the account is running. Wait a few seconds and send the call again.
- `daily_limit` (HTTP 429 in the API): the account has used all of its index searches for today.
- `backend_error` (HTTP 502 in the API): the search server did not answer, or its answer could not be read. Send the call again later. The call counts as 1 search.

### Limits

- The tool draws from the one daily count of index searches that every news_ and prospects_ tool of the account shares.
- Only one index search runs at a time per account: a call made while another one runs is refused (HTTP 429, `one_at_a_time`), so wait a few seconds and try again.
- `account_calls_left` shows the counts.
- A search that takes more than 10 seconds is stopped and answers HTTP 422, `search_stopped`, with a sentence that says how to make it more specific.
- A stopped search counts as 1 search.
- A call that is refused uses no daily search.

## Same data in the API

```http
POST /v1/news/search HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "campaign": 3,
  "similarity_target": "similarity_text",
  "similarity_text": "Boutique hotels winning direct bookings from younger travelers in mid-size US cities.",
  "similarity_score_min": 25,
  "title_query": "hotel",
  "published_from": "2026-11-01",
  "published_to": "2026-11-07",
  "sort": "best",
  "results_limit": 10
}
```

See [POST /v1/news/search](https://oppalerts.com/docs/api/news_search).

## Related pages

- [Advanced Search in the web app](https://oppalerts.com/docs/app/opportunities/advanced_search)
- [prospects_search: the same search on the Prospect Index](https://oppalerts.com/docs/mcp/prospects_search)
- [types_opportunity_types: the groups and types for type_scores](https://oppalerts.com/docs/mcp/types_opportunity_types)
- [types_content_types: the content types for type_scores](https://oppalerts.com/docs/mcp/types_content_types)
- [Use case: research industry news](https://oppalerts.com/docs/how-to/research-industry-news)
- [POST /v1/news/search in the API](https://oppalerts.com/docs/api/news_search)
