> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Get a story and its articles > Every distinct article of one story (the articles that report the same event), best sources first, with the number of newsrooms and when the first and the latest article appeared. Take the story id from the `story.id` of a search result. A successful request (HTTP 200) costs 1 NCC, regardless of the number of articles returned. The rate limits of your plan apply. ## OpenAPI ````yaml /api-reference/news-api/openapi.json get /stories/{story_id} openapi: 3.1.0 info: title: NewsCatcher News API summary: Ranked, story-aware news search. description: >- Search the news NewsCatcher has crawled in the last **30 days**, in every language: ranked by relevance, source authority and freshness, and grouped into **stories** (the articles that report the same event), with a one-line summary of each article. ## Authentication Send your API key in the `x-api-key` header of every request. Keys are created in the NewsCatcher platform. A missing or invalid key is answered with `401`. ## Endpoints | Endpoint | What it does | Charged | |---|---|---| | `GET` or `POST /search` | Ranked articles for a request in plain words or with keywords. | Yes, by effort | | `GET /stories/{story_id}` | Every article of one story. | Yes, 1 NCC per successful request | | `GET /subscription` | Your plan, limits and credit balance. | No | ## Effort and credits `effort` sets how much work goes into the ranking. A search is charged in **NCC** credits, by the effort you ask for, and only when it succeeds (`200`). | Effort | What it does | Credits | |---|---|---| | `low` | Ranks by relevance, authority, coverage and freshness. Fastest. | 1 | | `medium` (default) | Adds a cross-encoder rerank of the top stories. | 5 | | `high` | Adds an LLM judgement of the top stories and merges the stories that report the same event. Slowest, best quality. | 10 | A search that finds nothing is still charged. A request that is refused or fails (`401`, `402`, `403`, `422`, `429`, `500`, `503`) is never charged. ## Query `q` is a request in plain words or keywords, in any language, up to 500 characters. Put an upper-case `NOT` before a term to drop the articles that mention it in their headline, description or summary (`Apple NOT iPhone`). `languages`, `countries` and `sources` narrow the search; the time window is the last 7 days unless you set `search_window` (for example `15m`, `2h`, `1d`). ## Limits Your plan sets the requests per second (per effort level and in all), an optional daily limit, the most results per request (`limit`) and how far back you can search. `GET /subscription` returns all of them. Over a limit you get `429` with a `Retry-After` header. A `search_window` longer than your plan's history is cut to it and the response says `window.clamped`. ## Errors Every error has the same body: `message` (what went wrong), `status_code` and `status` (a short label). Use the HTTP status to decide what to do: | Status | Meaning | Retry the same request? | |---|---|---| | `401` | The API key is missing or invalid. | No | | `402` | Your credit balance does not cover the search. | After topping up | | `403` | The plan does not include what you asked for (a larger `limit`, an Enterprise field) or the key may not use this API. | No | | `404` | Unknown story. | No | | `422` | A parameter is missing, invalid or unknown, or the body is not valid JSON. | No, fix it first | | `429` | A rate limit of your plan. | Yes, after `Retry-After` seconds | | `500` | Something failed on our side. | Yes, and tell us the `Correlation-ID` | | `503` | A part of the service is temporarily unavailable. | Yes, after a short wait | Every response carries a `Correlation-ID` header (quote it to support) and an `X-Process-Time` header. ## Enterprise fields `include` adds heavy fields to every result (`description`, `entities`, `sentiment`, `themes`, `translation`, `embedding`). They are part of the Enterprise plans; other plans get `403` with `enterprise_field`. termsOfService: https://newscatcherapi.com/terms-of-service contact: name: NewsCatcher Support url: https://newscatcherapi.com/ email: support@newscatcherapi.com version: 1.0.0 servers: - url: https://api.newscatcherapi.com/news-api security: [] tags: - name: Search description: >- Search the news and read every article of a story. The articles are real news, ranked and grouped into stories. externalDocs: description: Search guide url: https://docs.newscatcherapi.com/ - name: Subscription description: Your plan, its limits and your credit balance. externalDocs: description: Plans and limits url: https://docs.newscatcherapi.com/ externalDocs: description: NewsCatcher documentation url: https://docs.newscatcherapi.com paths: /stories/{story_id}: get: tags: - Search summary: Get a story and its articles description: >- Every distinct article of one story (the articles that report the same event), best sources first, with the number of newsrooms and when the first and the latest article appeared. Take the story id from the `story.id` of a search result. A successful request (HTTP 200) costs 1 NCC, regardless of the number of articles returned. The rate limits of your plan apply. operationId: newsStoryGet parameters: - name: story_id in: path required: true schema: type: string description: 'Id of the story: the `story.id` of a search result (a UUID).' examples: - 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 description: 'Id of the story: the `story.id` of a search result (a UUID).' example: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 500 examples: - 50 default: 50 description: Number of articles to return (1 to 500). example: 50 responses: '200': description: The story and its articles. content: application/json: schema: $ref: '#/components/schemas/NewsStoryResponse' examples: story: summary: A story with its articles value: story_id: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 articles_total: 43 newsrooms: 40 first_seen: '2026-10-28T00:41:10+00:00' last_seen: '2026-10-28T13:58:02+00:00' articles: - id: 876a97d2bc58f3c2437ad7b03a06ebfe title: >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved language: en url: >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved domain: fox10tv.com published_at: '2026-10-28T01:05:37+00:00' content_type: news_report headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '401': description: The `x-api-key` header is missing, or the key is not valid. content: application/json: examples: missing_key: summary: Missing key value: message: >- The 'x-api-key' header is missing. Please provide your API key. status_code: 401 status: Unauthorized invalid_key: summary: Invalid key value: message: >- The 'x-api-key' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '402': description: >- Your credit balance does not cover the price of the search. Nothing was searched and nothing was charged. content: application/json: examples: insufficient_credits: summary: Insufficient credits value: message: >- Insufficient credits: a medium-effort search costs 5 NCC but your balance is 2 NCC. Please top up your credits. status_code: 402 status: Payment required schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '403': description: >- The request asks for more than your plan includes, or the key may not use the News API. content: application/json: examples: limit_above_plan: summary: Limit above plan value: message: >- Your plan allows up to 50 results per request, but you requested limit=51. status_code: 403 status: Forbidden enterprise_field: summary: Enterprise field value: message: >- enterprise_field: embedding is not included in your plan. Please upgrade to Enterprise. status_code: 403 status: Forbidden key_not_allowed: summary: Key not allowed value: message: >- This API key is not allowed to use the News API. Please check your account and organization access. status_code: 403 status: Forbidden other_product_key: summary: Other product key value: message: >- This API key belongs to another NewsCatcher product and cannot be used with the News API. Please use an API key from the NewsCatcher platform. status_code: 403 status: Forbidden schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '404': description: There is no story with this id. content: application/json: examples: unknown_story: summary: Unknown story value: message: Unknown story. status_code: 404 status: Not found schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '422': description: >- A parameter is missing, has the wrong type or an invalid value, is not a parameter of this endpoint, or the body is not valid JSON. The message names the parameter. Nothing was searched and nothing was charged. content: application/json: examples: invalid_value: summary: Invalid value value: message: The 'limit' parameter must be between 1 and 100. status_code: 422 status: Validation error missing_query: summary: Missing query value: message: '''q'' field required' status_code: 422 status: Validation error unknown_parameter: summary: Unknown parameter value: message: >- Invalid Parameter: 'mode'. Allowed parameters: q, effort, limit, collapse, sort_by, search_window, sources, languages, countries, not_sources, not_languages, not_countries, min_newsrooms, content_type, include. status_code: 422 status: Validation error invalid_country: summary: Invalid country value: message: >- Invalid country code(s): XX. Country codes must be valid ISO 3166-1 alpha-2 codes. status_code: 422 status: Validation error invalid_json: summary: Invalid json value: message: >- Invalid JSON format in request body. Please check your JSON syntax. status_code: 422 status: Validation error schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '429': description: >- You are over a rate limit of your plan: requests per second (per effort level, and in all) or requests per day. Wait for `Retry-After` seconds and send the request again; a refused request is not charged. headers: Retry-After: description: >- Seconds to wait before sending the request again: until the next second for the per-second limits, until 00:00 UTC for the daily limit. schema: type: integer minimum: 1 examples: - 1 Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' content: application/json: examples: per_second: summary: Per second value: message: >- Rate limit reached: your plan allows 1 requests per second for your organization. Please slow down and retry. status_code: 429 status: Too many requests per_day: summary: Per day value: message: >- Daily request limit reached: your plan allows 500 requests per day. The count restarts at 00:00 UTC. status_code: 429 status: Too many requests schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- Something failed on our side. Quote the `Correlation-ID` response header when you contact support. A failed request is not charged. content: application/json: examples: internal_error: summary: Internal error value: message: Internal server error occurred. Please contact support. status_code: 500 status: Internal error occurred schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '503': description: >- A part of the service is temporarily unavailable. Send the same request again after a short wait; it was not charged. content: application/json: examples: limits_unavailable: summary: Limits unavailable value: message: >- Request limits are temporarily unavailable. Please retry shortly. status_code: 503 status: Service unavailable search_unavailable: summary: Search unavailable value: message: The news search backend is not available. status_code: 503 status: Service unavailable schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' security: - ApiKeyAuth: [] components: schemas: NewsStoryResponse: properties: story_id: type: string description: Id of the story. examples: - 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 articles_total: type: integer minimum: 0 description: Number of distinct articles of the story. examples: - 43 newsrooms: type: integer minimum: 0 description: Number of newsrooms (distinct publishers) that cover the story. examples: - 40 first_seen: anyOf: - type: string format: date-time - type: 'null' description: Publication time of the earliest article (UTC, ISO 8601). examples: - '2026-10-28T00:41:10+00:00' last_seen: anyOf: - type: string format: date-time - type: 'null' description: Publication time of the latest article (UTC, ISO 8601). examples: - '2026-10-28T13:58:02+00:00' articles: items: $ref: '#/components/schemas/NewsStoryArticle' type: array description: The articles of the story, best sources first. type: object required: - story_id - articles_total - newsrooms - articles title: NewsStoryResponse description: A story and its articles. examples: - articles: - content_type: news_report domain: fox10tv.com id: 876a97d2bc58f3c2437ad7b03a06ebfe language: en published_at: '2026-10-28T01:05:37+00:00' title: >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved url: >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved articles_total: 43 first_seen: '2026-10-28T00:41:10+00:00' last_seen: '2026-10-28T13:58:02+00:00' newsrooms: 40 story_id: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 ErrorResponse: properties: message: type: string description: >- What went wrong and, where it helps, what to do about it. Meant to be read by a person; do not parse it. examples: - The 'limit' parameter must be between 1 and 100. status_code: type: integer description: The HTTP status code of the response, repeated. examples: - 422 status: type: string enum: - Bad request - Unauthorized - Payment required - Forbidden - Not found - Method not allowed - Payload too large - Validation error - Too many requests - Internal error occurred - Service unavailable description: Short label of the status code. examples: - Validation error type: object required: - message - status_code - status title: Error description: The body of every error response. examples: - message: The 'limit' parameter must be between 1 and 100. status: Validation error status_code: 422 NewsStoryArticle: properties: id: anyOf: - type: string - type: 'null' description: Article id. examples: - 876a97d2bc58f3c2437ad7b03a06ebfe title: type: string description: Headline as published. default: '' examples: - >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved language: anyOf: - type: string - type: 'null' description: Language of the article, an ISO 639-1 code. examples: - en url: type: string description: Link to the article. default: '' examples: - >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved domain: type: string description: Domain of the publisher. default: '' examples: - fox10tv.com published_at: anyOf: - type: string format: date-time - type: 'null' description: When the article was published (UTC, ISO 8601). examples: - '2026-10-28T01:05:37+00:00' content_type: type: string description: Type of content the article was classified as. default: news examples: - news_report type: object title: NewsStoryArticle description: One distinct article of a story. headers: Correlation-ID: description: >- Id of this request. Quote it when you contact support: it finds the request in our logs. schema: type: string format: uuid examples: - 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 X-Process-Time: description: Seconds the API spent on the request. schema: type: string examples: - '0.1884448528289795' securitySchemes: ApiKeyAuth: type: apiKey description: >- Your NewsCatcher API key, created in the NewsCatcher platform. Send it in the `x-api-key` header of every request. in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.