Documentation / API / prospects_unlinked_brand_mentions

prospects_unlinked_brand_mentions

POSThttps://api.oppalerts.com/v1/prospects/unlinked_brand_mentions

Lists the Prospect Index pages that name the brand and do not link to any of its sites.

What it does

The tool searches the Prospect Index for pages that name the brand of the campaign and do not link to any of its sites. You select the brand's own sites or the competitors' sites. Each result is one page, with its dates, its site metrics, its link counts, and its outbound links.

A page that names your brand without a link gives you a reason to request one. You can ask the site to add it.

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 your token in the Authorization: Bearer header. Authentication and Limits explains the tokens.

Parameters

The tool takes 26 parameters. link_counts_min and type_scores hold more fields. Each of these fields has its own entry below: a dotted name is a field inside an object, and [] marks a field of one item of a list.

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.
relationshiporg_owned_brand | org_competitor, required
Required. The organizations of the campaign whose sites the pages link to or name. org_owned_brand: the organizations that are the own brand of the campaign. org_competitor: the organizations that are its competitors.
indexed_daysint, optional, 1 to 3650
Optional. Keep the pages added to the index in the last N days, a whole number from 1 to 3650. Not sent: any time. Refused together with published_from, published_to, indexed_from, or indexed_to.
similarity_targetnone | campaign | similarity_text | saved_opportunity, required
Required. The vector: what the pages must be semantically similar to. none: no vector, and the other fields alone find the pages. campaign: the market description of the campaign. similarity_text: the text in similarity_text. saved_opportunity: the similarity text of the saved opportunity in similarity_target_opportunity. A target that has no text yet is refused. With a vector, each result has a similarity_score from 0 to 100.
similarity_target_opportunityint, required in some calls, 1 to 4294967295
Required when similarity_target is saved_opportunity, and refused with any other similarity_target. The id of a saved opportunity of the campaign, a whole number from 1 to 4294967295, from campaigns_saved_opportunities. The saved opportunity must have a similarity text. An id that is not in the campaign answers HTTP 404, opportunity_not_found.
similarity_textstring, required in some calls, max 20000 characters
Required when similarity_target is similarity_text, and refused with any other similarity_target. The text the pages must be semantically similar to, at most 20,000 characters. A text of only spaces is refused.
similarity_score_minint, optional, 1 to 100
Optional, and refused when similarity_target is none. The least similarity_score a result must have, a whole number from 1 to 100. Not sent: no minimum.
title_querystring, optional, max 500 characters
Optional. Words the title must have, at most 500 characters. It takes these search operators: AND, OR, MAYBE, NEAR/N, and NOTNEAR/N in capitals, the Negation operator (-), the Phrase search operator, the Proximity search operator (~N), the Exact form modifier (=), the IDF boost modifier (^N), the Wildcard operator (* at the end of a word), and Grouping with parentheses (one level). A wrong use is refused with a sentence that names the field. The full list is in Advanced Search Operators. At most 20 words or phrases: a text with more is refused, and nothing is cut. A text with no word or phrase, such as only OR or only spaces, is refused. Not sent: no title words.
body_querystring, optional, max 500 characters
Optional. Words the body must have, at most 500 characters, with the same rules as title_query. Not sent: no body words.
title_body_joinand | or, required in some calls
Required when you send both title_query and body_query, and refused when you send one of them or none. and: a page must match both. or: a page must match one of them.
published_fromstring, optional, YYYY-MM-DD
Optional. The first published 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 published_from after published_to. Refused together with indexed_days. Not sent: no first day.
published_tostring, optional, YYYY-MM-DD
Optional. The last published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused together with indexed_days. Not sent: no last day.
indexed_fromstring, optional, YYYY-MM-DD
Optional. The first day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused: a text in another form, and an indexed_from after indexed_to. Refused together with indexed_days. Not sent: no first day.
indexed_tostring, optional, YYYY-MM-DD
Optional. The last day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused together with indexed_days. Not sent: no last day.
pr_domain_minint, optional, 0 to 100
Optional. Keep the pages whose domain PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above pr_domain_max.
pr_domain_maxint, optional, 1 to 100
Optional. Keep the pages whose domain PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no domain PageRank stays in the results. 0 is refused. Not sent: no maximum.
pr_host_minint, optional, 0 to 100
Optional. Keep the pages whose host PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above pr_host_max.
pr_host_maxint, optional, 1 to 100
Optional. Keep the pages whose host PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no host PageRank stays in the results. 0 is refused. Not sent: no maximum.
prot_domain_minint, optional, 0 to 1000000
Optional. Keep the pages whose domain PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 applies no minimum. Not sent: no minimum. Refused when it is above prot_domain_max.
prot_domain_maxint, optional, 1 to 1000000
Optional. Keep the pages whose domain PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 is refused. Not sent: no maximum.
prot_host_minint, optional, 0 to 1000000
Optional. Keep the pages whose host PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 applies no minimum. Not sent: no minimum. Refused when it is above prot_host_max.
prot_host_maxint, optional, 1 to 1000000
Optional. Keep the pages whose host PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 is refused. Not sent: no maximum.
link_counts_minobject, optional
Optional. The least number of outbound links of each link type in each page section: {"article"|"nav"|"comments": {"follow"|"nofollow"|"sponsored"|"ugc": n}}. A result must have at least n links of that type in that section. Send only the sections and the link types that you want. Not sent: no minimum.
link_counts_min.articleobject, optional
Optional. The article section of the page.
link_counts_min.article.followint, optional, 0 to 4294967295
Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.nofollowint, optional, 0 to 4294967295
Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.sponsoredint, optional, 0 to 4294967295
Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.ugcint, optional, 0 to 4294967295
Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.navobject, optional
Optional. The navigation section of the page.
link_counts_min.nav.followint, optional, 0 to 4294967295
Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.nofollowint, optional, 0 to 4294967295
Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.sponsoredint, optional, 0 to 4294967295
Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.ugcint, optional, 0 to 4294967295
Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.commentsobject, optional
Optional. The comments section of the page, where visitors add content.
link_counts_min.comments.followint, optional, 0 to 4294967295
Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.nofollowint, optional, 0 to 4294967295
Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.sponsoredint, optional, 0 to 4294967295
Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.ugcint, optional, 0 to 4294967295
Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
type_scoreslist of objects, optional, max 20 items
Optional. The types a result must score on, 1 to 20 items. Each item is an object with an opportunity_type or a content_type, and its type_score_min. A result must pass every item. A type named 2 times is refused. Not sent: no type filter. A result of this tool has no type_scores key: only news_search and prospects_search answer type_scores, with the score of each type that the call sends.
type_scores[].opportunity_typestring, optional
An opportunity type as <group>/<type>, for example advertising/newsletter-ads, from types_opportunity_types. An item has an opportunity_type or a content_type, not both. A type that does not exist is refused.
type_scores[].content_typestring, optional
A content type, for example blogs, from types_content_types. An item has a content_type or an opportunity_type, not both. A type that does not exist is refused.
type_scores[].type_score_minint, required, 1 to 100
Required. The least type score the page must have for this type, a whole number from 1 to 100. 0 is refused.
sortrelevance | similarity | indexed | published, required
Required. The order of the results. relevance: the strongest match first, of the brand search and of title_query and body_query when you send them. similarity: the nearest in semantic similarity first; refused when similarity_target is none. indexed: the newest day added to the index first. published: the newest published day first.
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 the maximum of your plan is refused, and the error gives that maximum.

Rules

  • The search looks for each brand name and each host name of the organization, as an exact phrase, in the title and the body.
  • relationship is required.
  • similarity_target is required: send none for no vector.
  • similarity_text is required with similarity_target similarity_text, and similarity_target_opportunity with saved_opportunity; each one is refused with another similarity_target.
  • similarity_score_min and sort similarity are refused with similarity_target none.
  • title_body_join is required when you send both title_query and body_query, and refused otherwise.
  • sort relevance works with no title_query and no body_query: the brand search is a match of its own, and relevance orders by it.
  • A from date after its to date is refused, and so is a minimum above its maximum.
  • A date field together with indexed_days is refused.
  • When the search cannot run, for example when the campaign has no organization of that relationship, the call is refused with cannot_run (HTTP 409) and a sentence that says why. It uses no daily search.
  • partial is true when more than 15,000 pages match a search with a vector: results then comes from only part of the matches.
  • With similarity_target none, partial is always false.
  • When partial is true, make the search more specific: use more exact words, a higher minimum PR, a higher minimum type score, or a shorter date range.

Response fields

The response holds these top-level fields:

  • relationship: the relationship of the request, org_owned_brand or org_competitor.
  • organizations: the organizations of the campaign with that relationship. Each has its hosts.
  • partial: true when results comes from only part of the matches, and false when it comes from all of them. The Rules above say when it is true and what to do.
  • results: the pages.

Each item of results is one page. It has id, url, host, document_type, published_at, indexed_at, pr_host, prot_host, pr_domain, prot_domain, similarity_score, relevance_weight, org, and page. The object page holds title, snippet, link_counts, meta, and sections. The page sections are article, nav, and comments. Each section of page.sections holds links, emails, phones, and service_accounts.

A result has similarity_score only with a vector. A result has org only when its site is an organization of the campaign.

Example

Request

curl -X POST https://api.oppalerts.com/v1/prospects/unlinked_brand_mentions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign": 3,
  "relationship": "org_owned_brand",
  "indexed_days": 30,
  "similarity_target": "none",
  "sort": "published"
}'

Response

The full sample answer.

{
  "relationship": "org_owned_brand",
  "organizations": [
    {
      "hosts": [
        "example-hotels.com"
      ]
    }
  ],
  "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 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.
  • bad_param also refuses a title_query or a body_query with no word or phrase, such as only OR or only spaces.
  • bad_param also refuses a title_query or a body_query with a formatting error, a wrong use of one of the search operators. The sentence names the field and the error, and the query is not searched.
  • no_campaign: HTTP 404. The campaign is not a campaign of your account.
  • opportunity_not_found: HTTP 404. The id in similarity_target_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 search cannot run now, for example the campaign has no organization of that relationship, or similarity_target is campaign and the campaign has no Campaign vector 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 the maximum of your plan 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 prospects_unlinked_brand_mentions gives the same data. See prospects_unlinked_brand_mentions in MCP.