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

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / news_opportunities

# news_opportunities

`POST https://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](https://oppalerts.com/docs/api/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](https://oppalerts.com/docs/api/account_calls_left) shows the searches that are left today.

## Authentication

Send an API token in the `Authorization: Bearer` header. See [the API overview](https://oppalerts.com/docs/api/).

## 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.

**`campaign`int, 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.

**`opportunity`int, 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_from`string, 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_to`string, 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_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 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

```bash
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.

```json
{
  "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

**`opportunity`object**

The saved opportunity: its `id` and its `label`.

**`date_from`, `date_to`string**

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_counted`bool, 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_indexes`object**

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.

**`partial`bool**

True when `results` comes from only part of the matches. The Rules section above explains when.

**`results`list**

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
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](https://oppalerts.com/docs/mcp/news_opportunities).

## Related pages

- [campaigns_saved_opportunities: the opportunity ids](https://oppalerts.com/docs/api/campaigns_saved_opportunities)
- [prospects_opportunities: the same list on the Prospect Index](https://oppalerts.com/docs/api/prospects_opportunities)
- [news_search: search the News Index with your own fields](https://oppalerts.com/docs/api/news_search)
- [news_opportunities in MCP](https://oppalerts.com/docs/mcp/news_opportunities)
