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

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

# news_similar_to_id

`POST https://api.oppalerts.com/v1/news/similar_to_id`

Lists the News Index documents most semantically similar to a document identified by its document_id.

## What it does

The tool takes the id of one News Index document in `document_id`, a string of digits. Take the id from a result of a News Index search. It returns that document as `document`, and the 100 documents nearest in semantic similarity as `results`, nearest first. Copies of the same text on other sites are not merged: each copy is a separate result. `found` is true when the index has the document and its vector. When `found` is false, `document` holds empty values, and `results` is an empty list.

Use it to go from one page that you found to more pages like it.

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/api/account_calls_left) shows the searches that are left today.

## Authentication

Send a token in the `Authorization: Bearer` header. [Authentication and Limits](https://oppalerts.com/docs/api/) explains the tokens.

## Parameters

Send the parameters as a JSON object in the request body. The route has 2 parameters, with each part of an object counted one by one.

**`campaign`int, optional, 1 to 4294967295**

Optional. The campaign id, a whole number from 1 to 4294967295, from `campaigns_list`. When you send it, the campaign must be in this account, and a result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. When you do not send it, no result has an org key.

**`document_id`string of digits, required**

Required. The document id, from a search result: a decimal string of 1 to 20 digits. It is a string because the value exceeds the largest whole number that JavaScript can represent exactly.

### Rules

- found is true when the index has the document and its vector.
- When found is false, document holds empty values, and results is an empty list.
- No field has a default value.
- A field that you do not send applies no condition.

## Example

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/news/similar_to_id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign": 3,
  "document_id": "1152921504611003120"
}'
```

### Response

The full sample answer.

```json
{
  "found": true,
  "document": {
    "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"
            }
          ]
        }
      }
    }
  },
  "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"
              }
            ]
          }
        }
      }
    }
  ]
}
```

## 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.
- 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 has an HTTP status and a JSON body with `error`, the error code, and `error_description`, the message. An example: a call that sends `days`, a field that this route does not have.

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error": "bad_param", "error_description": "days is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."}
```

- `bad_param` (HTTP 400): 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.
- `no_campaign` (HTTP 404): the campaign is not a campaign of your account.
- `search_stopped` (HTTP 422): 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): another index search of the account is running. Wait a few seconds and send the call again.
- `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.

### 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 tool in MCP

The MCP tool `news_similar_to_id` gives the same data. Read the [MCP page of news_similar_to_id](https://oppalerts.com/docs/mcp/news_similar_to_id).

## Related pages

- [Similar News in the web app](https://oppalerts.com/docs/app/opportunities/similar_news)
- [news_similar_to_id in MCP](https://oppalerts.com/docs/mcp/news_similar_to_id)
- [prospects_similar_to_id: the same search on the Prospect Index](https://oppalerts.com/docs/api/prospects_similar_to_id)
- [news_search](https://oppalerts.com/docs/api/news_search)
- [Use case: find content ideas](https://oppalerts.com/docs/how-to/find-content-ideas)
- [Use case: research industry news](https://oppalerts.com/docs/how-to/research-industry-news)
