Documentation / MCP / prospects_search
prospects_search
POSThttps://mcp.oppalerts.com/mcptool: prospects_search
Search the Prospect Index, the wider-web collection, with the same fields that news_search takes: by semantic similarity, by words in titles and bodies, or both, with date, type, rank, and outbound-link filters.
What it does
The tool searches the Prospect Index, the wider-web collection. It takes the same fields as news_search. You can search by semantic similarity (similarity_target), by words in the titles and bodies (title_query, body_query), or by both.
You can filter by date, document type, rank, and outbound links, and by opportunity type or content type score (type_scores). Each result then has type_scores, its score for each type that you send, and sort type_score puts the highest score of one type first. Prospect results also carry their stored outbound-link counts.
A call with similarity_target none, no title_query, and no body_query is refused.
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 shows
the searches that are left today.
Connect
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 has the details.
Parameters
The tool takes 25 parameters. link_counts_min and type_scores hold more fields. Each of these fields has its own entry below: a dotted name is a field inside an object, and [] marks a field of one item of a list.
campaignint, 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_targetcampaignandsaved_opportunityneed a campaign. similarity_targetnone | 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 insimilarity_text.saved_opportunity: the similarity text of the saved opportunity insimilarity_target_opportunity. A target that has no text yet is refused. With a vector, each result has asimilarity_scorefrom 0 to 100. similarity_target_opportunityint, required in some calls, 1 to 4294967295- Required when
similarity_targetissaved_opportunity, and refused with any othersimilarity_target. The id of a saved opportunity of the campaign, a whole number from 1 to 4294967295, fromcampaigns_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_textstring, required in some calls, max 20000 characters- Required when
similarity_targetissimilarity_text, and refused with any othersimilarity_target. The text the pages must be semantically similar to, at most 20,000 characters. A text of only spaces is refused. similarity_score_minint, optional, 1 to 100- Optional, and refused when
similarity_targetisnone. The leastsimilarity_scorea result must have, a whole number from 1 to 100. Not sent: no minimum. title_querystring, optional, max 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. 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_querystring, optional, max 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_joinand | or, required in some calls- Required when you send both
title_queryandbody_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_fromstring, optional, YYYY-MM-DD- 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_fromafterpublished_to. Not sent: no first day. published_tostring, optional, YYYY-MM-DD- 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_fromstring, optional, YYYY-MM-DD- 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_fromafterindexed_to. Not sent: no first day. indexed_tostring, optional, YYYY-MM-DD- 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_typepage | podcast | video, optional- Optional. The document type to search:
page,podcast, orvideo. Not sent: all 3. pr_domain_minint, 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_maxint, 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_minint, 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_maxint, 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_minint, 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_maxint, 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_minint, 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_maxint, 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_minobject, 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.articleobject, optional- Optional. The article section of the page.
link_counts_min.article.followint, 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.nofollowint, 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.sponsoredint, 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.ugcint, 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.navobject, optional- Optional. The navigation section of the page.
link_counts_min.nav.followint, 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.nofollowint, 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.sponsoredint, 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.ugcint, 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.commentsobject, optional- Optional. The comments section of the page, where visitors add content.
link_counts_min.comments.followint, 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.nofollowint, 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.sponsoredint, 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.ugcint, 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_scoreslist of objects, optional, max 20 items- Optional. The types a result must score on, 1 to 20 items. Each item is an object with an
opportunity_typeor acontent_type, and itstype_score_min. A result must pass every item. A type named 2 times is refused. Not sent: no type filter. When you sendtype_scores, each result has the keytype_scores, with the score of the result for each type that you sent. sorttype_scoretakes exactly 1 item. type_scores[].opportunity_typestring, optional- An opportunity type as
<group>/<type>, for exampleadvertising/newsletter-ads, fromtypes_opportunity_types. An item has anopportunity_typeor acontent_type, not both. A type that does not exist is refused. type_scores[].content_typestring, optional- A content type, for example blogs, from
types_content_types. An item has acontent_typeor anopportunity_type, not both. A type that does not exist is refused. type_scores[].type_score_minint, 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.
sortbest | 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 whensimilarity_targetisnone.relevance: the strongest word match first; refused with notitle_queryand nobody_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 intype_scoresfirst;type_scoresmust hold exactly 1 item, so sorttype_scoreis refused with notype_scoresand with 2 or more items. results_limitint, 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
- Prospect results also have their stored outbound link counts.
similarity_targetis required: sendnonefor no vector.similarity_textis required withsimilarity_targetsimilarity_text, andsimilarity_target_opportunitywithsaved_opportunity; each one is refused with anothersimilarity_target.similarity_score_minandsortsimilarityare refused withsimilarity_targetnone.title_body_joinis required when you send bothtitle_queryandbody_query, and refused otherwise.sortrelevanceis refused with notitle_queryand nobody_query.sorttype_scoreis refused whentype_scoresdoes not hold exactly 1 item.- A call with
similarity_targetnone, notitle_query, and nobody_queryis refused. - A from date after its to date is refused, and so is a minimum above its maximum.
partialis true when more than 15,000 pages match a search with a vector:resultsthen comes from only part of the matches.- When
partialis true, make the search more specific: use more exact words, a higher minimum PR, a higher minimum type score, or a shorter date range. returnedis the number of results in this answer.- When you send
type_scores, each result hastype_scores, with its score for each of those types. - No field of the answer gives the number of all the matches.
Example
Call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "prospects_search",
"arguments": {
"campaign": 3,
"similarity_target": "none",
"title_query": "hotel",
"body_query": "advertise",
"title_body_join": "and",
"indexed_from": "2026-11-01",
"indexed_to": "2026-11-07",
"document_type": "page",
"pr_domain_min": 10,
"sort": "relevance",
"results_limit": 10
}
}
}
Response
The full sample answer.
{
"returned": 83,
"partial": false,
"results": [
{
"id": "2305843009217850096",
"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
}
]
}
}
The answer has these top-level fields: returned (the number of results), partial (true when results comes from only part of the matches; the Rules above say when), results, and contacts. The contacts field lists the social accounts, emails, and phones that the results carry, with a count for each. The social accounts are grouped by page section: head, nav, article, and comments. Each result is one page of the Prospect Index. With a vector, each result has a similarity_score from 0 to 100. When the call sends type_scores, each result has type_scores: the score of the page for each type that the call sends, as a map of the type to its score, from 0 to 100.
Errors
bad_param: HTTP 400. A field is unknown, empty, of the wrong type, or out of its range, or the call breaks a rule of this page. The message names the field.bad_paramalso refuses atitle_queryor abody_querywith no word or phrase, such as onlyORor only spaces.bad_paramalso refuses atitle_queryor abody_querywith a formatting error, a character that is not allowed (How to Search the Indexes) or a wrong use of one of the search operators. The sentence names the field and the error, and the query is not searched.no_campaign: HTTP 404. The campaign is not a campaign of your account.opportunity_not_found: HTTP 404. The id insimilarity_target_opportunityis not a saved opportunity of the campaign.one_at_a_time: HTTP 429. Another index search of the account is running. Wait a few seconds and send the call again. A refused call uses no daily call.daily_limit: HTTP 429. The account has used all of its index searches for today.backend_error: HTTP 502. The search server did not answer, or its answer could not be read. Send the call again later. The call counts as 1 search.search_stopped: HTTP 422. The search took more than 10 seconds and the server stopped it. The message says how to make the search more specific. A stopped search counts as 1 search.
In MCP, an error is a tool result with isError set to true. Its text starts with the error code, then the message.
Limits
- Each call draws from the one daily count of index searches that every
news_andprospects_tool of the account shares. account_calls_left shows the counts. - Only one index search runs at a time per account.
- A call that is refused uses no daily search. A search that is stopped at 10 seconds counts as 1 search.
- A
results_limitabove the maximum of your plan is refused, and the error gives that maximum.
Strict Rules
- An unknown field is refused, also inside an object. A field name of an older version of this tool is an unknown field.
- A bad value is refused: a value of the wrong type, a value out of its range, a value that is not in its list, and an empty text, list, or object. To send no value, leave the field out.
- The error names the field.
- 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. - 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 example: the result of a call that sends the field limit, which this tool does not have.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "bad_param: limit is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
}
],
"isError": true
}
}
Same data in the API
POST /v1/prospects/search HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{"campaign": 3, "similarity_target": "none", "title_query": "hotel", "body_query": "advertise", "title_body_join": "and", "indexed_from": "2026-11-01", "indexed_to": "2026-11-07", "document_type": "page", "pr_domain_min": 10, "sort": "relevance", "results_limit": 10}
See POST /v1/prospects/search in the API.