Documentation / API / prospects_opportunities
prospects_opportunities
POSThttps://api.oppalerts.com/v1/prospects/opportunities
The pages found on the Prospect 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 Prospect 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 Prospect 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.
Authentication
Send an API token in the Authorization: Bearer header. The API page shows how to get a token.
Parameters
The tool takes 5 parameters.
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, YYYY-MM-DD- 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, YYYY-MM-DD- 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 Prospect Index in that window.
- 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. - One call is 1 index search, for 1 day or for 7 days.
Example
Request
curl -X POST https://api.oppalerts.com/v1/prospects/opportunities \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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": "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"
}
]
}
}
}
}
]
}
The answer has these top-level fields: opportunity (its id and its label), date_from, date_to, not_counted_yet, stored_count, stored_count_partial, stored_count_not_counted, counts_by_day (one item for each day, with count, partial, and not_counted), counts_by_day_both_indexes (the same items for both indexes added together), partial, and results. The Rules above explain each field. Each result is one page of the Prospect Index, with the fields of a search result.
The example shows every key that the answer can have.
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.no_campaign: HTTP 404. The campaign is not a campaign of your account.opportunity_not_found: HTTP 404. The id inopportunityis 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.cannot_run: HTTP 409. 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. 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.
The API answers with the HTTP status and a JSON body: error holds the error code, and error_description holds 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 your plan’s maximum 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 answer (HTTP 400) to a call that sends the field limit, which this tool does not have.
{
"error": "bad_param",
"error_description": "limit is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
}
Same tool in MCP
The MCP tool is prospects_opportunities. See prospects_opportunities in MCP.