> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search articles by links or IDs > Searches for articles based on specified links or IDs. You can filter results by date range. ## OpenAPI ````yaml news-api-v3 get /api/search_by_link openapi: 3.1.0 info: title: NewsCatcher News API description: > NewsCatcher News API provides programmatic access to a continuously updated global news index. It includes endpoints for article search, latest headlines, breaking news, author search, aggregation counts, and source discovery. ## Key features - **Full-text search**: Query articles by keyword, phrase, language, country, source, publication date, sentiment, and more using Boolean operators and advanced filters. - **NLP enrichment**: Articles include theme classification, sentiment scores, and named entity recognition (people, organizations, locations). - **Article clustering**: Group similar articles into clusters to reduce noise and surface unique stories. - **Deduplication**: Exclude duplicate articles from results to keep datasets clean and relevant. - **Source intelligence**: Discover and filter news sources by domain, type, rank, and geographic origin. For documentation, integration guides, and SDKs, visit the [developer portal](https://wwwnewscatcherapi.com/docs). termsOfService: https://newscatcherapi.com/terms-of-service contact: name: Maksym Sugonyaka email: maksym@newscatcherapi.com version: 3.24.0 servers: - url: https://v3-api.newscatcherapi.com description: News API production server security: - ApiKeyAuth: [] tags: - name: Search description: Operations to search for articles. externalDocs: description: Search for articles by keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search/search-articles-get - name: LatestHeadlines description: Operations to retrieve latest headlines. externalDocs: description: >- Retrieve the latest headlines since a specified date, with filtering options. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/latest-headlines/retrieve-latest-headlines-get - name: BreakingNews description: Operations to retrieve breaking news articles. externalDocs: description: Retrieve breaking news articles. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/breaking-news/breaking-news-get - name: Authors description: Operations to search by author. externalDocs: description: Search for articles by author. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/authors/search-articles-by-author-get - name: SearchByLink description: Operations to search by link or ID. externalDocs: description: Search for articles by link or ID. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search-by-link/search-articles-by-links-or-ids-get - name: Sources description: Operations to retrieve news sources. externalDocs: description: >- Retrieve the list of available sources, filtered by language and country. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/sources/retrieve-sources-get - name: AggregationCount description: Operations to aggregate news counts. externalDocs: description: >- Aggregate news counts based on specified criteria such as keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/aggregation-count/get-aggregation-count-by-interval-get - name: Subscription description: Operations to get subscription info. externalDocs: description: Retrieve information about your subscription plan. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/subscription/retrieve-subscription-plan-information-get externalDocs: description: Find out more about NewsCatcher News API url: https://www.newscatcherapi.com/docs paths: /api/search_by_link: get: tags: - SearchByLink summary: Search articles by links or IDs description: >- Searches for articles based on specified links or IDs. You can filter results by date range. operationId: searchByLinkGet parameters: - $ref: '#/components/parameters/Ids' - $ref: '#/components/parameters/Links' - name: from_ in: query required: false schema: allOf: - $ref: '#/components/schemas/From' default: 1 month ago - $ref: '#/components/parameters/To' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/RobotsCompliant' responses: '200': $ref: '#/components/responses/SearchByLinkResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '408': $ref: '#/components/responses/RequestTimeoutError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' components: parameters: Ids: description: > 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. **Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time. name: ids in: query required: false schema: type: string example: 5f8d0d55b6e45e00179c6e7e Links: description: > The article link or list of article links to search for. To specify multiple links, use a comma-separated string. **Caution**: You can use either the `links` or the `ids` parameter, but not both at the same time. name: links in: query required: false schema: type: string example: https://nytimes.com/article1,https://bbc.com/article2 To: name: to_ in: query required: false schema: $ref: '#/components/schemas/To' Page: name: page in: query required: false schema: $ref: '#/components/schemas/Page' PageSize: name: page_size in: query required: false schema: $ref: '#/components/schemas/PageSize' RobotsCompliant: name: robots_compliant in: query required: false schema: $ref: '#/components/schemas/RobotsCompliant' schemas: From: oneOf: - type: string format: date-time example: '2024-07-01T00:00:00.000Z' - type: string example: 1 day ago default: 7 days ago description: > 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` - Duration shorthand: `7d`, `30d`, `24h`, `48h` **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`. example: 2021/01/01 To: oneOf: - type: string example: now - type: string format: date-time example: '2024-01-01T00:00:00.000Z' description: > 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` - Duration shorthand: `7d`, `30d`, `24h`, `48h` **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`. default: now Page: type: integer minimum: 1 default: 1 description: > 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 [Retrieve large datasets](https://www.newscatcherapi.com/docs/news-api/how-to/retrieve-more-than-10k-articles) example: 2 PageSize: type: integer minimum: 1 maximum: 1000 default: 100 description: | The number of articles to return per page. example: 50 RobotsCompliant: type: boolean description: > If true, returns only articles that comply with the publisher's robots.txt rules. If false, returns only articles that do not comply with robots.txt rules. If omitted, returns all articles regardless of compliance status. example: true SearchResponseDto: title: Search Response description: > 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. allOf: - $ref: '#/components/schemas/BaseSearchResponseDto' - type: object properties: articles: $ref: '#/components/schemas/ArticlesDto' user_input: $ref: '#/components/schemas/UserInputDto' Error: type: object properties: message: type: string description: A detailed description of the error. status_code: type: integer description: The HTTP status code of the error. status: type: string description: A short description of the status code. required: - message - status_code - status BaseSearchResponseDto: title: Base Search Response description: The base response model containing common fields for search operations. required: - status - total_hits - page - total_pages - page_size type: object properties: status: title: Status description: The status of the response. type: string total_hits: title: Total Hits description: The total number of articles matching the search criteria. type: integer page: title: Page description: The current page number of the results. type: integer total_pages: title: Total Pages description: The total number of pages available for the given search criteria. type: integer page_size: title: Page Size description: The number of articles per page. type: integer ArticlesDto: title: Articles description: A list of articles matching the search criteria. type: array items: $ref: '#/components/schemas/ArticleEntity' default: [] UserInputDto: type: object description: The user input parameters for the request. additionalProperties: true ArticleEntity: title: Article Object description: The data model representing a single article in the search results. required: - title - link - domain_url - full_domain_url - parent_url - rank - id - score type: object properties: title: title: Title description: The title of the article. type: string author: title: Author description: The primary author of the article. type: string authors: title: Authors description: A list of authors of the article. anyOf: - type: array items: type: string - type: string journalists: title: Journalists description: A list of journalists associated with the article. anyOf: - type: array items: type: string - type: string - type: 'null' published_date: title: Published Date description: The date the article was published. type: string published_date_precision: title: Published Date Precision description: The precision of the published date. type: string updated_date: title: Updated Date description: The date the article was last updated. type: - string - 'null' updated_date_precision: title: Updated Date Precision description: The precision of the updated date. type: - string - 'null' parse_date: title: Parse Date description: The date the article was parsed. type: - string - 'null' link: title: Link description: The URL link to the article. type: string domain_url: title: Domain URL description: The domain URL of the article. type: string full_domain_url: title: Full Domain URL description: The full domain URL of the article. type: string name_source: title: Name Source description: The name of the source where the article was published. type: string is_headline: title: Is Headline description: Indicates if the article is a headline. type: boolean paid_content: title: Paid Content description: >- Indicates whether the source labels the article as paywalled or requiring a subscription for full access. type: boolean parent_url: title: Parent URL description: The categorical URL of the article. type: string country: title: Country description: The country where the article was published. type: string rights: title: Rights description: The rights information for the article. type: string rank: title: Rank description: The rank of the article's source. type: integer media: title: Media description: The media associated with the article. type: string language: title: Language description: The language in which the article is written. type: string description: title: Description description: A brief description of the article. type: string content: title: Content description: The content of the article. type: string title_translated_en: type: - string - 'null' description: > English translation of the article title. Available when using the `search_in` parameter with the `title_translated` option or by setting the `include_translation_fields` parameter to `true`. content_translated_en: type: - string - 'null' description: > English translation of the article content. Available when using the `search_in` parameter with the `content_translated` option or by setting the `include_translation_fields` parameter to `true`. word_count: title: Word Count description: The word count of the article. type: integer default: 0 is_opinion: title: Is Opinion description: Indicates if the article is an opinion piece. type: boolean twitter_account: title: Twitter Account description: The Twitter account associated with the article. type: - string - 'null' all_links: title: All Links description: A list of all URLs mentioned in the article. anyOf: - type: array items: type: string - type: string default: [] all_domain_links: title: All Domain Links description: A list of all domain URLs mentioned in the article. anyOf: - type: array items: type: string - type: string default: [] all_links_data: title: All Links Data description: > Detailed information about all links mentioned in the article, including link URL, domain, and anchor text. Only present when the `all_links_text` parameter is used in the request. type: array items: $ref: '#/components/schemas/AllLinksDataItem' default: [] nlp: $ref: '#/components/schemas/NlpDataEntity' id: title: ID description: The unique identifier for the article. type: string score: title: Score description: The relevance score of the article. type: number robots_compliant: title: Robots Compliant description: > True if the article content can be safely accessed according to the publisher's robots.txt rules; false otherwise. type: boolean example: true custom_tags: title: Custom Tags description: >- An object that contains custom tags associated with an article, where each key is a taxonomy name, and the value is an array of tags. type: object additionalProperties: type: array items: type: string default: {} additional_domain_info: $ref: '#/components/schemas/AdditionalDomainInfoEntity' AllLinksDataItem: title: Link Data Item description: Detailed information about a link found in an article. required: - domain_url - link - text type: object properties: domain_url: title: Domain URL description: The domain of the linked URL. type: string example: amazon.de link: title: Link description: The complete URL of the link. type: string example: https://www.amazon.de/s?k=Künstliche+Intelligenz text: title: Text description: The anchor text of the link. type: string example: KI Brillen NlpDataEntity: type: object default: {} description: Natural Language Processing data for the article. properties: translation_summary: type: string description: | A brief AI-generated summary of the article's English translation. theme: type: string description: The themes or categories identified in the article. summary: type: string description: A brief AI-generated summary of the article content. sentiment: $ref: '#/components/schemas/SentimentScores' new_embedding: type: array items: type: number format: float description: > A dense 1024-dimensional vector representation of the article content, generated using the [multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large) model. Available for articles indexed before January 1, 2026. **Note**: The `new_embedding` field is only available in the `v3_nlp_embeddings` subscription plan. qwen_embedding: type: array items: type: number format: float description: > A dense 1024-dimensional vector representation of the article content, generated using the [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding) model. Available for articles indexed from January 1, 2026 onward. Embeddings are computed from a combination of the article `title` and `content` fields. **Note**: The `qwen_embedding` field is only available in the `v3_nlp_embeddings` subscription plan. ner_PER: allOf: - $ref: '#/components/schemas/NamedEntityList' description: Named Entity Recognition for person entities (individuals' names). ner_ORG: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for organization entities (company names, institutions). ner_MISC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for miscellaneous entities (events, nationalities, products). ner_LOC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for location entities (cities, countries, geographic features). translation_ner_PER: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for person entities (individuals' names) extracted from the English translation of the article. translation_ner_ORG: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for organization entities (company names, institutions) extracted from the English translation of the article. translation_ner_MISC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for miscellaneous entities (events, nationalities, products) extracted from the English translation of the article. translation_ner_LOC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for location entities (cities, countries, geographic features) extracted from the English translation of the article. iptc_tags_name: type: array items: type: string description: > IPTC media topic taxonomy paths identified in the article content. Each path represents a hierarchical category following the IPTC standard. **Note**: The `iptc_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan. iptc_tags_id: type: array items: type: string description: > IPTC media topic numeric codes identified in the article content. These codes correspond to the standardized IPTC media topic taxonomy. **Note**: The `iptc_tags_id` field is only available in the `v3_nlp_iptc_tags` subscription plan. iab_tags_name: type: array items: type: string description: > IAB content taxonomy paths identified in the article content. Each path represents a hierarchical category following the IAB content standard. **Note**: The `iab_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan. AdditionalDomainInfoEntity: title: Additional Domain Info description: Additional information about the domain of the article. type: object properties: is_news_domain: title: Is News Domain description: Indicates whether the domain is a news domain. type: boolean news_type: title: News Type description: The type of news content provided by the domain. type: string news_domain_type: title: News Domain Type description: The type of news domain. type: string example: is_news_domain: true news_type: News and Blogs news_domain_type: Original Content SentimentScores: type: object description: Sentiment scores for the article's title and content. properties: title: type: number format: float description: The sentiment score for the article title (-1.0 to 1.0). content: type: number format: float description: The sentiment score for the article content (-1.0 to 1.0). NamedEntityList: type: array description: A list of named entities identified in the article. items: type: object properties: entity_name: type: string description: The name of the entity identified in the article. count: type: integer description: The number of times this entity appears in the article. responses: SearchByLinkResponse: description: >- A successful response containing articles that match the provided links or IDs. content: application/json: schema: $ref: '#/components/schemas/SearchResponseDto' BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid JSON in request body status_code: 400 status: Bad request UnauthorizedError: description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The 'x-api-token' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized ForbiddenError: description: Forbidden - Server refuses action content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Your plan request date range cannot be greater than 400 days status_code: 403 status: Forbidden RequestTimeoutError: description: Request timeout content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Request timed out after 30 seconds status_code: 408 status: Request timeout ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid date format status_code: 422 status: Validation error RateLimitError: description: Too many requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Max API requests concurrency reached status_code: 429 status: Too many requests InternalServerError: description: Internal server error content: text/plain: schema: type: string example: Internal Server Error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token description: > 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](https://www.newscatcherapi.com/book-a-demo) or contact us directly. ````