Documentation / MCP / news_opportunities
news_opportunities
POSThttps://mcp.oppalerts.com/mcptool: news_opportunities
The pages found on the News Index for one saved opportunity on the days from date_from to date_to, 1 to 7 days: the same search that the nightly count ran, across the combined daily windows for those days.
What it does
A saved opportunity of a campaign has a search that the nightly count runs every day. This tool returns the pages that the search finds on the News Index on 1 to 7 days, from date_from to date_to, across the combined daily windows for those days. For one day, send the same day as date_from and date_to.
You find the opportunity ids with campaigns_saved_opportunities. The response also includes the stored daily counts: counts_by_day for the News Index, and counts_by_day_both_indexes for both indexes added together. The Rules section below explains each count.
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 has 5 parameters, with each part of an object counted one by one. Send them as the arguments of the tool call.
campaignint, required, 1 to 4294967295- Required. The campaign id, a whole number from 1 to 4294967295, from
campaigns_list. The campaign must be in this account. A result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. opportunityint, required, 1 to 4294967295- Required. The id of a saved opportunity of the campaign, a whole number from 1 to 4294967295, from
campaigns_saved_opportunities. An id outside the campaign results in HTTP 404,opportunity_not_found. date_fromstring, required, at most 10 characters- Required. The first day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. The window of a day is the 24 hours that end at 09:00 UTC on that day. Refused: a text in another form, and a
date_fromafterdate_to. date_tostring, required, at most 10 characters- Required. The last 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
date_tomore than 6 days afterdate_from: the range is at most 7 days,date_fromanddate_toincluded. For one day, send the same day asdate_from. 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 your plan’s maximum is refused, and the error gives that maximum.
Rules
- The window of a day is the 24 hours that end at 09:00 UTC on that day, the window of the nightly count.
- A page is in a day when it was added to the News Index in that window.
- A page must also be published in the 7 days that end at 09:00 UTC on
date_to. - For one day, send the same day as
date_fromanddate_to. - A
date_fromafterdate_tois refused, and so is a range of more than 7 days. - The opportunity ids come from
campaigns_saved_opportunities. counts_by_dayholds the stored daily counts of this index,stored_countis the sum of the stored counts of the days fromdate_fromtodate_to, andnot_counted_yetis true when none of those days has a stored count yet.- Each day of
counts_by_dayhas its count, partial, andnot_counted. partialis true when more than 15,000 pages matched on that day: that count then comes from only part of the matches, and the real number can be higher.not_countedis true when that count stopped with an error, for example when the index stopped the search at 10 seconds: the count is then 0, but no count was taken.stored_count_partialis true when one of the days fromdate_fromtodate_tois partial, andstored_count_not_countedis true when one of those days was not counted: the sum then leaves that day out.counts_by_day_both_indexesholds the stored daily counts of both indexes added together.- For each day, count is the sum of the counts that were taken,
partialis true when one of them is partial, andnot_countedis true when neither index was counted. - When the search cannot run, for example when the saved opportunity has nothing to search for, the call is refused with
cannot_run(HTTP 409) and a sentence that says why. It uses no daily search. partialis true when the saved opportunity has a vector and more than 15,000 pages match its search in this window:resultsthen comes from only part of the matches.- When
partialis true, make the saved opportunity more specific withcampaigns_saved_opportunity_update: use more exact words, a higher minimum PR, or a higher minimum type score. - 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.
- One call is 1 index search, for 1 day or for 7 days.
Example
Call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "news_opportunities",
"arguments": {
"campaign": 3,
"opportunity": 1,
"date_from": "2026-08-26",
"date_to": "2026-09-01"
}
}
}
Response
The full sample answer.
{
"opportunity": {
"id": 1,
"label": "Guest posts"
},
"date_from": "2026-08-26",
"date_to": "2026-09-01",
"not_counted_yet": false,
"stored_count": 26,
"stored_count_partial": false,
"stored_count_not_counted": false,
"counts_by_day": {
"2026-09-01": {
"count": 17,
"partial": false,
"not_counted": false
},
"2026-08-31": {
"count": 9,
"partial": false,
"not_counted": false
}
},
"counts_by_day_both_indexes": {
"2026-09-01": {
"count": 23,
"partial": false,
"not_counted": false
},
"2026-08-31": {
"count": 15,
"partial": false,
"not_counted": false
}
},
"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"
}
]
}
}
}
}
]
}
The example shows every key.
Fields of the response
opportunityobject- The saved opportunity: its
idand itslabel. date_from,date_tostring- The first day and the last day of the call, as YYYY-MM-DD.
not_counted_yet,stored_count,stored_count_partial,stored_count_not_countedbool, int, bool, bool- The stored counts of the days from
date_fromtodate_to. The Rules section above explains each one. counts_by_day,counts_by_day_both_indexesobject- One item for each day, with
count,partial, andnot_counted: the stored daily counts of the News Index, and of both indexes added together. partialbool- True when
resultscomes from only part of the matches. The Rules section above explains when. resultslist- One item for each page.
Each item of results has these fields:
id,url,host,document_type- The document id (a string of digits), its URL, its host, and its document type: page, podcast, or video.
published_at,indexed_at- The time the page was published, and the time it was added to the index, as ISO 8601 text in UTC, for example 2026-05-10T00:00:00Z.
pr_host,prot_host,pr_domain,prot_domain- The PageRank and the PRoT of the host of the page and of its domain. PRoT (PageRank over Time) is the sum of the monthly PageRank values.
similarity_score- With a vector, how semantically similar the page is to the vector, from 0 to 100.
type_scores- This tool returns no
type_scoreskey. Onlynews_searchandprospects_searchreturn it, when the call sendstype_scores. relevance_weight- The relevance weight of the page.
org- What the site of the page is to the campaign, in
org.relationship:org_owned_brand,org_competitor,org_partner, ororg_publisher. Left out when the site is not an organization of the campaign. page- The page
title, asnippet(the first 400 characters of the body),link_countsfor each section (article,nav, andcomments) and each link type (follow,nofollow,sponsored, andugc),meta(the favicon, the feeds, and the contact pages), andsections: the outboundlinks,emails,phones, andservice_accountsfound in each section. Each link hasurl,text,title,rel, andorgwhen the linked site is an organization of the campaign.
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.
- 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.
{
"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. Aresults_limitabove your plan’s maximum 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.cannot_run(HTTP 409 in the API): the saved opportunity cannot run now, for example it uses the Campaign vector and the campaign has none yet. The sentence says why. The call uses no daily search.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_leftshows 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
POST /v1/news/opportunities HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"campaign": 3,
"opportunity": 1,
"date_from": "2026-08-26",
"date_to": "2026-09-01"
}
See POST /v1/news/opportunities.