Documentation / API / news_opportunities

news_opportunities

POSThttps://api.oppalerts.com/v1/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.

Authentication

Send an API token in the Authorization: Bearer header. See the API overview.

Parameters

Send the parameters as a JSON object in the request body. The route has 5 parameters, with each part of an object counted one by one.

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_from after date_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_to more than 6 days after date_from: the range is at most 7 days, date_from and date_to included. For one day, send the same day as date_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_from and date_to.
  • A date_from after date_to is refused, and so is a range of more than 7 days.
  • The opportunity ids come from campaigns_saved_opportunities.
  • counts_by_day holds the stored daily counts of this index, stored_count is the sum of the stored counts of the days from date_from to date_to, and not_counted_yet is true when none of those days has a stored count yet.
  • Each day of counts_by_day has its count, partial, and not_counted.
  • partial is 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_counted is 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_partial is true when one of the days from date_from to date_to is partial, and stored_count_not_counted is true when one of those days was not counted: the sum then leaves that day out.
  • counts_by_day_both_indexes holds the stored daily counts of both indexes added together.
  • For each day, count is the sum of the counts that were taken, partial is true when one of them is partial, and not_counted is 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.
  • partial is true when the saved opportunity has a vector and more than 15,000 pages match its search in this window: results then comes from only part of the matches.
  • When partial is true, make the saved opportunity more specific with campaigns_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

Request

curl -X POST https://api.oppalerts.com/v1/news/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": "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 id and its label.
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_from to date_to. The Rules section above explains each one.
counts_by_day, counts_by_day_both_indexesobject
One item for each day, with count, partial, and not_counted: the stored daily counts of the News Index, and of both indexes added together.
partialbool
True when results comes 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_scores key. Only news_search and prospects_search return it, when the call sends type_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, or org_publisher. Left out when the site is not an organization of the campaign.
page
The page title, a snippet (the first 400 characters of the body), link_counts for each section (article, nav, and comments) and each link type (follow, nofollow, sponsored, and ugc), meta (the favicon, the feeds, and the contact pages), and sections: the outbound links, emails, phones, and service_accounts found in each section. Each link has url, text, title, rel, and org when 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 has an HTTP status and a JSON body with error, the error code, and error_description, the message. An example: a call that sends days, a field that this route does not have.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error": "bad_param", "error_description": "days is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."}
  • bad_param (HTTP 400): 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 your plan’s maximum is refused too.
  • no_campaign (HTTP 404): the campaign is not a campaign of your account.
  • opportunity_not_found (HTTP 404): the saved opportunity is not in the campaign.
  • search_stopped (HTTP 422): 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): another index search of the account is running. Wait a few seconds and send the call again.
  • 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.

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 tool in MCP

The MCP tool is news_opportunities. See news_opportunities.