Skip to main content
GET
/
api
/
search_by_link
Search articles by links or IDs
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: 7 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, now
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
​
robots_compliant
boolean

If true, returns only articles/sources that comply with the publisher's robots.txt rules. If false, returns only articles/sources that do not comply with robots.txt rules. If omitted, returns all articles/sources regardless of compliance status.

Response

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.
​
status
string
required

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
Article Object · object[]

A list of articles matching the search criteria.

​
user_input
object

The user input parameters for the request.