POST
/
api
/
search_by

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.

Body

application/json
​
links

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

Examples:

  • "https://example.com/article1, https://example.com/article2"
  • ["https://example.com/article1", "https://example.com/article2"]

Note: You can use the links parameter in combination with ids or rss_guids, but at least one of these parameters must be provided.

​
ids

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

Examples:

  • "1234567890abcdef, abcdef1234567890"
  • ["1234567890abcdef", "abcdef1234567890"]

Note: You can use the ids parameter in combination with links or rss_guids, but at least one of these parameters must be provided.

​
rss_guids

The RSS GUID (Globally Unique Identifier) or list of GUIDs to search for. To specify multiple GUIDs, use a comma-separated string or an array of strings.

GUIDs are unique identifiers assigned to RSS feed items. They are often URLs or other unique strings.

Examples:

  • "https://example.com/article1,https://example.com/article2"
  • ["https://example.com/article1", "https://example.com/article2"]
  • "1234567890abcdef,abcdef1234567890"

Note: You can use the rss_guids parameter in combination with links or ids, but at least one of these parameters must be provided.

​
from_
default: 7 days 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-09-24T00:00:00
  • YYYY-MM-dd: 2024-09-24
  • YYYY/mm/dd HH:MM:SS: 2024/09/24 00:00:00
  • YYYY/mm/dd: 2024/09/24
  • English phrases: 1 day ago, today

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

​
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-09-25T00:00:00
  • YYYY-MM-dd: 2024-09-25
  • YYYY/mm/dd HH:MM:SS: 2024/09/25 00:00:00
  • YYYY/mm/dd: 2024/09/25
  • English phrases: 1 day ago, today, now

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

​
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, Latest headlines, and Search by 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.).
​
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[]

A list of articles matching the search criteria.

​
user_input
object

The user input parameters for the search.

Was this page helpful?

Retrieve sources