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

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

# news_brand_links

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

Lists the News Index pages that link to the sites of your campaign's brand, or to the sites of its competitors.

## What it does

The tool searches the News Index for pages with a link to a site of the campaign. You select the brand's own sites or the competitors' sites. Each result is one page, with its link counts and site metrics.

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/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 has 44 parameters, with each part of an object counted one by one. Send them as the `arguments` of the tool call.

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

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

**`published_days`int, optional, 1 to 90**

Optional. Keep the pages published in the last N days, a whole number from 1 to 90. Not sent: any time. Refused together with `published_from`, `published_to`, `indexed_from`, or `indexed_to`.

**`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 cases, 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 cases, at most 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, at most 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, at most 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 cases**

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, at most 10 characters**

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 `published_days`. Not sent: no first day.

**`published_to`string, optional, at most 10 characters**

Optional. The last published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused together with `published_days`. Not sent: no last day.

**`indexed_from`string, optional, at most 10 characters**

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 `published_days`. Not sent: no first day.

**`indexed_to`string, optional, at most 10 characters**

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 `published_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, 1 to 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

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

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "news_brand_links",
    "arguments": {
      "campaign": 3,
      "relationship": "org_owned_brand",
      "published_days": 30,
      "similarity_target": "none",
      "sort": "published"
    }
  }
}
```

### Response

The full sample answer.

```json
{
  "relationship": "org_owned_brand",
  "organizations": [
    {
      "hosts": [
        "example-hotels.com"
      ]
    }
  ],
  "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

**`relationship`string**

The value of the `relationship` parameter that the search used: `org_owned_brand` or `org_competitor`.

**`organizations`list**

The organizations that the search looked for, each with its `hosts`.

**`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 near the page is in semantic similarity to the vector, from 0 to 100.

**`type_scores`**

This tool answers no `type_scores` key. Only `news_search` and `prospects_search` answer 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.

![Claude shows the answer of news_brand_links as a short list of pages.](https://oppalerts.com/img/docs/mcp/news_brand_links/claude-code-answer.png)

*Claude uses news_brand_links to answer the question "Which news pages linked to my brand this month?"*

## 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.
- A `title_query` or `body_query` with no word or phrase, such as only OR or only spaces, is refused.
- A `title_query` or `body_query` with a formatting error, a wrong use of one of the [search operators](https://oppalerts.com/docs/the-data/advanced-search-operators), is refused with a sentence that names the field and the error. The query is not searched.
- 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 returns as a tool result with `isError` true. Its text starts with the error code. An example: a call that sends `days`, a field that this tool does not have.

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

- `bad_param` (HTTP 400 in the API): 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 the maximum of your plan is refused too.
- `no_campaign` (HTTP 404 in the API): the campaign is not a campaign of your account.
- `opportunity_not_found` (HTTP 404 in the API): the saved opportunity is not in the campaign.
- `search_stopped` (HTTP 422 in the API): 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 in the API): another index search of the account is running. Wait a few seconds and send the call again.
- `cannot_run` (HTTP 409 in the API): 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 in the API): the account has used all of its index searches for today.
- `backend_error` (HTTP 502 in the API): 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 data in the API

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

{
  "campaign": 3,
  "relationship": "org_owned_brand",
  "published_days": 30,
  "similarity_target": "none",
  "sort": "published"
}
```

The API page is [POST /v1/news/brand_links](https://oppalerts.com/docs/api/news_brand_links).

## Related pages

- [Brand Links in the web app](https://oppalerts.com/docs/app/visibility/brand_links)
- [Competitor Links in the web app](https://oppalerts.com/docs/app/visibility/competitor_links)
- [POST /v1/news/brand_links in the API](https://oppalerts.com/docs/api/news_brand_links)
- [prospects_brand_links: the same search on the Prospect Index](https://oppalerts.com/docs/mcp/prospects_brand_links)
- [Use case: monitor new brand links](https://oppalerts.com/docs/how-to/monitor-new-brand-links)
