GET
/
api
/
search_by_link
curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/search_by_link \
  --header 'x-api-token: <api-key>'
{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [],
  "user_input": {}
}

Authorizations

​
x-api-token
string
header
required

API Key to authenticate requests.

To access the API, include your API key in the x-api-token header. To obtain your API key, complete the form or contact us directly.

Query Parameters

​
ids
string

The Newscatcher article ID (corresponds to the _id field in API response) or a list of article IDs to search for. To specify multiple IDs, use a comma-separated string.

Example: "1234567890abcdef, abcdef1234567890"

Caution: You can use either the links or the ids parameter, but not both at the same time.

​
links
string

The article link or list of article links to search for. To specify multiple links, use a comma-separated string.

Example: "https://example.com/article1, https://example.com/article2"

Caution: You can use either the links or the ids parameter, but not both at the same time.

​
from_
default:1 month ago

The starting point in time to search from. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

  • YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
  • YYYY-MM-dd: 2024-07-01
  • YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
  • YYYY/mm/dd: 2024/07/01
  • English phrases: 1 day ago, today
Example:

"2021/01/01"

​
to_
default:now

The ending point in time to search up to. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

  • YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
  • YYYY-MM-dd: 2024-07-01
  • YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
  • YYYY/mm/dd: 2024/07/01
  • English phrases: 1 day ago, today
Example:

"2021/12/31"

​
page
integer
default:1

The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles.

For details, see How to paginate large datasets.

Required range: x >= 1
​
page_size
integer
default:100

The number of articles to return per page.

Required range: 1 <= x <= 1000

Response

200
application/json
A successful response containing articles that match the provided links or IDs.

The response model for the search requests applies to the Search, Latest Headlines, Search by link, and Authors endpoints. Response field behavior:

  • Required fields are guaranteed to be present and non-null.
  • Optional fields may be null or undefined if the data point is not presented or couldn't be extracted during processing.
  • To access article properties in the articles response array, use array index notation. For example, articles[n].title, where n is the zero-based index of the article object (0, 1, 2, etc.).
  • The nlp property within the article object articles[n].nlp is only available with NLP-enabled subscription plans.