Documentation / API / news_similar_to_id
news_similar_to_id
POSThttps://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 shows the searches that are left today.
Authentication
Send a token in the Authorization: Bearer header. Authentication and Limits 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.
campaignint, 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_idstring 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
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.
{
"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/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_leftshows 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.