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_from after date_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_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 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

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

{
  "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.