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

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / prospects_brand_link_gap

# prospects_brand_link_gap

`POST https://mcp.oppalerts.com/mcp tool: prospects_brand_link_gap`

Lists the Prospect Index pages that link to your competitors, on sites that link to none of your own sites.

## What it does

The tool searches the Prospect Index for the link gap. A page qualifies when it links to a competitor of the campaign and its site links to none of the campaign's own sites. Each result names the competitors it links to, in `competitors_linked`.

Use it to find sites that already link to your competitors and not to you.

All `news_` and `prospects_` tools of one account share one daily count of index searches, and the OppAlerts website uses the same count. Only one index search runs at a time. [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows the searches that are left today.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

The tool takes 27 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.

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

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

**`sections`list of strings, optional**

Optional. The page sections where a qualifying link can be: `article`, `nav`, `comments`. Not sent: all 3. An unknown value is refused.

**`link_types`list of strings, optional**

Optional. The link types that qualify: `follow`, `nofollow`, `sponsored`, `ugc`. Not sent: all 4. An unknown value is refused.

**`similarity_target`none | 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_opportunity`int, 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_text`string, 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_min`int, 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_query`string, 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](https://oppalerts.com/docs/the-data/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_query`string, 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_join`and | 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_from`string, 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_to`string, 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_from`string, 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_to`string, 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_min`int, 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_max`int, 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_min`int, 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_max`int, 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_min`int, 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_max`int, 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_min`int, 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_max`int, 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_min`object, 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.article`object, optional**

Optional. The article section of the page.

**`link_counts_min.article.follow`int, 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.nofollow`int, 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.sponsored`int, 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.ugc`int, 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.nav`object, optional**

Optional. The navigation section of the page.

**`link_counts_min.nav.follow`int, 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.nofollow`int, 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.sponsored`int, 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.ugc`int, 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.comments`object, optional**

Optional. The comments section of the page, where visitors add content.

**`link_counts_min.comments.follow`int, 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.nofollow`int, 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.sponsored`int, 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.ugc`int, 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_scores`list 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_type`string, 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_type`string, 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_min`int, 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.

**`sort`relevance | 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_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 the maximum of your plan is refused, and the error gives that maximum.

### Rules

- Each result has `competitors_linked`: the first host of each competitor organization that the page links to, the same text as hosts[0] of that organization in organizations.
- 3 facts about the test of which sites already link to your sites: `indexed_days` also limits the pages that this test reads; `results_limit` applies before the test, so fewer results than `results_limit` can come back; and the test reads the News Index, not the Prospect Index.
- `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.
- When the search cannot run, because the campaign has no competitor with a website, the call is refused with `cannot_run` (HTTP 409) and a sentence that says why. It uses no daily search.
- A date field together with `indexed_days` is refused.
- `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.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "prospects_brand_link_gap",
    "arguments": {
      "campaign": 3,
      "indexed_days": 30,
      "similarity_target": "none",
      "pr_domain_min": 10,
      "sort": "published"
    }
  }
}
```

### Response

The full sample answer.

```json
{
  "organizations": [
    {
      "hosts": [
        "grand-resorts.example"
      ]
    },
    {
      "hosts": [
        "cozyinns.example"
      ]
    }
  ],
  "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"
              }
            ]
          }
        }
      },
      "competitors_linked": [
        "cozyinns.example",
        "grand-resorts.example"
      ]
    }
  ]
}
```

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](https://oppalerts.com/docs/the-data/advanced-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.

In MCP, an error is a tool result with `isError` set to `true`. Its text starts with the error code, then 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/mcp/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 result of a call that sends the field `limit`, which this tool does not have.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "bad_param: limit is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
      }
    ],
    "isError": true
  }
}
```

## Same data in the API

```http
POST /v1/prospects/brand_link_gap HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"campaign": 3, "indexed_days": 30, "similarity_target": "none", "pr_domain_min": 10, "sort": "published"}
```

Read the [API page of prospects_brand_link_gap](https://oppalerts.com/docs/api/prospects_brand_link_gap).

## Related pages

- [Brand Link Gap in the web app](https://oppalerts.com/docs/app/opportunities/brand_link_gap)
- [POST /v1/prospects/brand_link_gap in the API](https://oppalerts.com/docs/api/prospects_brand_link_gap)
- [news_brand_link_gap: the same search on the News Index](https://oppalerts.com/docs/mcp/news_brand_link_gap)
- [backlinks_link_gap](https://oppalerts.com/docs/mcp/backlinks_link_gap)
- [prospects_brand_links](https://oppalerts.com/docs/mcp/prospects_brand_links)
- [Use case: find competitor backlink gaps](https://oppalerts.com/docs/how-to/find-competitor-backlink-gaps)
- [Use case: prioritize link prospects](https://oppalerts.com/docs/how-to/prioritize-link-prospects)
