> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Get subscription info > Your plan, its limits and your credit balance: what one search costs per effort level, the requests per second and per day your organization may send (and how many it has used today), the largest `limit`, how many days back you can search, the heavy fields you can `include`, and the NCC credits you have left. Free: it is not charged. The balance is cached for up to 2 minutes and usage reaches it 1 to 3 minutes late. ## OpenAPI ````yaml /api-reference/news-api/openapi.json get /subscription 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: /subscription: get: tags: - Subscription summary: Get subscription info description: >- Your plan, its limits and your credit balance: what one search costs per effort level, the requests per second and per day your organization may send (and how many it has used today), the largest `limit`, how many days back you can search, the heavy fields you can `include`, and the NCC credits you have left. Free: it is not charged. The balance is cached for up to 2 minutes and usage reaches it 1 to 3 minutes late. operationId: subscriptionGet responses: '200': description: Your plan, limits and balance. content: application/json: schema: $ref: '#/components/schemas/OrganizationSubscriptionResponse' 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' '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: OrganizationSubscriptionResponse: properties: plan: type: string description: Code of your subscription plan. examples: - platform_free max_articles_per_page: type: integer description: Largest `limit` your plan allows; a larger one is refused with 403. examples: - 50 historical_days: type: integer description: >- How many days back your plan allows searching; a longer `search_window` is cut to it. examples: - 30 requests_per_second: $ref: '#/components/schemas/EffortRates' description: >- Requests per second allowed for your whole organization, per effort level. shared_requests_per_second: anyOf: - type: integer - type: 'null' description: >- Requests per second allowed for your organization across all effort levels, if limited. examples: - 1 daily_request_limit: anyOf: - type: integer - type: 'null' description: >- Requests allowed per UTC day, if limited. Null when your plan has no daily limit. examples: - 500 daily_requests_used: type: integer description: Requests counted today (UTC). examples: - 12 credits_per_search: $ref: '#/components/schemas/EffortCredits' description: NCC one successful search costs, per effort level. story: $ref: '#/components/schemas/StoryAccess' description: >- Story pages: whether your plan allows them, their requests per second and their price. extra_fields: items: type: string enum: - description - entities - sentiment - themes - translation - embedding type: array description: >- Heavy article fields your plan unlocks with `include`. Empty when your plan has none. examples: - - entities - sentiment credits_balance: anyOf: - type: integer - type: number description: >- Remaining NCC credits. Cached for up to 2 minutes, and usage reaches it 1 to 3 minutes late. examples: - 8950 type: object required: - plan - max_articles_per_page - historical_days - requests_per_second - daily_requests_used - credits_per_search - story - extra_fields - credits_balance title: OrganizationSubscriptionResponse description: Plan, limits and credits of the authenticated organization. examples: - credits_balance: 8950 credits_per_search: high: 10 low: 1 medium: 5 daily_request_limit: 500 daily_requests_used: 12 extra_fields: [] historical_days: 30 max_articles_per_page: 50 plan: platform_free requests_per_second: high: 1 low: 1 medium: 1 shared_requests_per_second: 1 story: credits_per_request: 1 enabled: true requests_per_second: 1 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 EffortRates: properties: low: type: integer description: Requests per second for `low` effort searches. examples: - 1 medium: type: integer description: Requests per second for `medium` effort searches. examples: - 1 high: type: integer description: Requests per second for `high` effort searches. examples: - 1 type: object required: - low - medium - high title: EffortRates description: Requests per second per effort level. EffortCredits: properties: low: anyOf: - type: integer - type: number description: NCC a successful `low` effort search costs. examples: - 1 medium: anyOf: - type: integer - type: number description: NCC a successful `medium` effort search costs. examples: - 5 high: anyOf: - type: integer - type: number description: NCC a successful `high` effort search costs. examples: - 10 type: object required: - low - medium - high title: EffortCredits description: Credits per effort level. StoryAccess: properties: enabled: type: boolean description: >- Whether your plan allows story pages; when it does not they are refused with 403. examples: - true requests_per_second: type: integer description: >- Story requests per second allowed for your whole organization. 0 when story pages are not enabled. examples: - 1 credits_per_request: anyOf: - type: integer - type: number description: >- NCC a successful story request costs, whatever the number of articles returned. examples: - 1 type: object required: - enabled - requests_per_second - credits_per_request title: StoryAccess description: Story pages (`GET /stories/{story_id}`) on your plan. 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.