GET
/
api
/
search_by_link

Authorizations

​
x-api-token
string
headerrequired

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
required

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"

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

​
links
string
required

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"

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

​
from_
string
default: 1 month ago

The starting point in time to search from. The publication date of the article is used. The default time zone is UTC. Available formats:

  • YYYY/mm/dd
  • YYYY/mm/dd HH:MM:SS
  • English phrases like 1 day ago.
​
to_
string
default: now

The ending point in time to search up to. The publication date of the article is used. The default time zone is UTC. Available formats:

  • YYYY/mm/dd
  • YYYY/mm/dd HH:MM:SS
  • English phrases like 1 day ago.
​
page
integer
default: 1

The page number to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.

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

The number of articles to return per page. Range: 1 to 1000.

Required range: 1 < x < 1000

Response

200 - application/json

The response model for the Search and Search by link requests, including search results and metadata.

Response field behavior:

  • Required fields are guaranteed to be present and non-null.
  • Optional fields may be null/undefined if the data 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.
​
status
string
default: okrequired

The status of the response.

​
total_hits
integer
required

The total number of articles matching the search criteria.

​
page
integer
required

The current page number of the results.

​
total_pages
integer
required

The total number of pages available for the given search criteria.

​
page_size
integer
required

The number of articles per page.

​
articles
object[]
required

A list of articles matching the search criteria.

​
user_input
object
required

The user input parameters for the search.

Was this page helpful?

Search articles by authorSearch articles by links or IDs