---
title: "Get articles by URL or ID"
method: GET
path: "/api/search_by_link"
tags: ["SearchLink"]
---

# Get articles by URL or ID

`GET /api/search_by_link`

## Request

- Base URL: `https://v3-api.newscatcherapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://v3-api.newscatcherapi.com/api/search_by_link`
- Auth: none declared. Required headers: `x-api-token`

Fetch specific articles directly by their NewsCatcher article id(s) or by their exact article link(s), instead of running a full-text search. Provide either ids or links (the two are mutually exclusive and cannot be combined in the same request).

## Query parameters

- `ids` unknown
- `links` unknown
- `from_` union: Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 1 month ago if omitted - a longer default window than other endpoints, since this endpoint fetches specific known articles rather than searching recent news.
  - string
  - string, date-time
- `to_` union: End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted.
  - string
  - string, date-time
- `page` integer: Page number of results to return, starting at 1.
- `page_size` integer: Number of articles per page. Integer between 1 and 1000.
- `include_translation_fields` union: Includes machine-translated title/content fields (title_translated_en, content_translated_en) in the response for non-English articles. Automatically enabled if search_in includes a '_translated' field.
  - string
  - boolean

## Headers

- `x-api-token` string, required: Your NewsCatcher API key, used to authenticate this request.

## Response `200`

Successful Response

- SearchResponse: SearchResponse DTO class.
  - `status` string: Always 'ok' for a successful search.
  - `total_hits` integer, required: Total number of articles matching the query, across all pages.
  - `page` integer, required: Current page number returned.
  - `total_pages` integer, required: Total number of pages available for this query, given page_size.
  - `page_size` integer, required: Number of articles returned per page.
  - `articles` object[], required: Articles matching the query for this page.
  - `user_input` object, required: Echo of the request parameters that produced this response.

## Other responses

- `401`: Missing or invalid `x-api-token` header.
- `403`: A supplied parameter isn't included in your subscription plan, or the requested date range exceeds your plan's allowed history window. Also returned to free tier (trial) keys whose trial has ended or whose included calls are used up.
- `408`: Your query reached the search backend but did not finish within 30 seconds. Narrow the date range, lower page_size, or simplify the query. Note this covers only genuinely slow queries - if the backend could not be reached at all the response is 503, which is retryable as-is.
- `422`: Request validation failed, e.g. an invalid parameter value or a missing required field.
- `429`: Rate limit exceeded for your plan.
- `499`: The HTTP status line is 499, but the response body's own `status_code` field reads 422 - a known quirk of this API's validation-error handling for cases not covered by the standard 422 path, not a documentation error.
- `503`: The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.

---

[API](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api.md) - [All operations](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/llms.txt) - [OpenAPI document](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/revisions/a3950aefb3e5?raw)