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

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

# prospects_opportunities

`POST https://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](https://oppalerts.com/docs/api/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](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. [The API page](https://oppalerts.com/docs/api/) shows how to get a token.

## Parameters

The tool takes 5 parameters.

**`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, 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_from` after `date_to`.

**`date_to`string, 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_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 Prospect Index in that window.
- 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.
- One call is 1 index search, for 1 day or for 7 days.

## Example

### Request

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

```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": "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 in `opportunity` is 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_` and `prospects_` tool of the account shares. [account_calls_left](https://oppalerts.com/docs/api/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_limit` above 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.

```json
{
  "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](https://oppalerts.com/docs/mcp/prospects_opportunities).

## Related pages

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