> ## Documentation Index > Fetch the complete documentation index at: https://docs.context.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search Company News > Search live and historical company news by name, domain, ticker, or ISIN. 1 Credit Per 10 Results ## OpenAPI ````yaml POST /news/search openapi: 3.1.0 info: title: Context API description: API for retrieving context data from any website version: 1.0.0 servers: - url: https://api.context.dev/v1 security: [] tags: - name: Batch description: Scrape many pages or crawl a site asynchronously. - name: Monitors description: >- Monitor pages, sitemaps, and extracted website data for exact or semantic changes. Webhook payloads are documented by the MonitorsChangeDetectedWebhookPayload and MonitorsRunCompletedWebhookPayload schemas. - name: WebDBs description: Create structured tables from web pages and keep them up to date. - name: News description: >- Search live first-party RSS and free historical news data by company identity. paths: /news/search: post: tags: - News summary: Search company news description: >- Searches live and historical company news for one company, identified in searchBy by name, domain, ticker (optionally disambiguated by exchange), or ISIN. Results can be filtered by publisher domain, publisher country, article language, article type, and published-at date, and include stable story IDs, source metadata, verified entity relevance, and cursor pagination. requestBody: required: true content: application/json: schema: type: object properties: searchBy: type: object properties: type: type: string enum: - entity description: How to search. Only entity search is supported. entity: oneOf: - $ref: '#/components/schemas/NewsSearchEntityByName' - $ref: '#/components/schemas/NewsSearchEntityByDomain' - $ref: '#/components/schemas/NewsSearchEntityByTicker' - $ref: '#/components/schemas/NewsSearchEntityByIsin' discriminator: propertyName: type mapping: name: $ref: '#/components/schemas/NewsSearchEntityByName' domain: $ref: '#/components/schemas/NewsSearchEntityByDomain' ticker: $ref: '#/components/schemas/NewsSearchEntityByTicker' isin: $ref: '#/components/schemas/NewsSearchEntityByIsin' description: >- The company to search news for, identified by name, domain, ticker, or ISIN. required: - type - entity additionalProperties: false description: What to search for. filterBy: type: object properties: sourceDomain: type: array items: type: string minLength: 1 maxLength: 253 minItems: 1 maxItems: 3 description: Publisher domains to include. Up to 3. sourceCountry: type: array items: type: string enum: - ae - ar - au - ca - cg - ch - cl - de - fi - fr - gb - hk - il - in - jp - kr - mx - ng - nl - qa - sa - se - sg - us - za minItems: 1 maxItems: 3 description: >- Publisher countries to include, as lowercase ISO 3166-1 alpha-2 codes. Up to 3. articleLanguage: type: array items: type: string enum: - ar - de - en - es - fr - hi - it - ja - ko - nl - pt - ru - zh minItems: 1 maxItems: 3 description: Article languages to include. Up to 3. articleType: type: array items: type: string enum: - editorial - press_release - regulatory_filing - advisory minItems: 1 maxItems: 3 description: Article types to include. Up to 3. date: type: object properties: from: type: integer description: >- Inclusive start of the published-at window, in epoch milliseconds. to: type: integer description: >- Inclusive end of the published-at window, in epoch milliseconds. additionalProperties: false description: Published-at window in epoch milliseconds. default: {} additionalProperties: false description: Optional result filters. sortBy: type: object properties: type: type: string enum: - relevance - newest description: Result ordering. default: type: newest required: - type additionalProperties: false description: Result ordering. Defaults to newest. limit: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum results to return. Defaults to 10. cursor: type: - string - 'null' maxLength: 300 description: >- Opaque next_cursor from the previous response, or null for the first page. tags: $ref: '#/components/schemas/RequestTags' required: - searchBy additionalProperties: false responses: '200': description: Company news results headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string description: >- Stable unique identifier for this article. Use it to deduplicate or reference an article across requests. story_id: type: string description: >- Shared by articles covering the same story on the same day. Use it to group or collapse syndicated copies of one announcement across outlets. url: type: string format: uri description: Link to the article on the publisher site. title: type: string description: Article headline. description: type: - string - 'null' description: >- Short summary or excerpt of the article, when the publisher provides one. language: type: - string - 'null' description: >- Language the article is written in, as a lowercase ISO 639-1 code such as en. Null when unknown. authors: type: array items: type: string description: Bylined authors. Empty when no byline is available. image_url: type: - string - 'null' description: Lead image for the article, when one is available. published_at: type: - string - 'null' format: date-time description: >- When the article was published, as an ISO 8601 timestamp. Null when the publisher does not state a reliable date. type: type: string enum: - editorial - press_release - regulatory_filing - advisory description: >- Kind of coverage. Use it to separate independent reporting (editorial) from company-issued content (press_release, regulatory_filing, advisory). source: type: object properties: name: type: string description: Name of the publication, such as Reuters. domain: type: string description: Website domain of the publication. direct: type: boolean description: >- True when Context observed this article in the publisher-owned feed. required: - name - domain - direct description: The publication that published the article. match: type: object properties: level: type: string enum: - primary - secondary description: >- primary when the article is mainly about the company, secondary when the company is mentioned but is not the main subject. confidence: type: - number - 'null' minimum: 0 maximum: 1 description: >- How confident the match is, from 0 to 1. Null when a score is unavailable. required: - level - confidence description: >- How the article relates to the company you searched for. required: - id - story_id - url - title - description - language - authors - image_url - published_at - type - source - match description: Articles matching the search, in the requested order. has_more: type: boolean description: True when more results are available beyond this page. next_cursor: type: - string - 'null' description: >- Pass as cursor in the next request to fetch the following page. Null when there are no more results. meta: type: object properties: count: type: integer minimum: 0 description: Number of articles in this page. required: - count description: Summary information about this response. key_metadata: $ref: '#/components/schemas/KeyMetadata' required: - data - has_more - next_cursor - meta '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': description: Request exceeded the applicable rate limit. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- News search failed because the index or an upstream resolver was unavailable. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: JavaScript source: |- import ContextDev from 'context.dev'; const client = new ContextDev({ apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted }); const response = await client.news.search({ searchBy: { entity: { name: 'xx', type: 'name' }, type: 'entity', }, }); console.log(response.data); - lang: Python source: |- import os from context.dev import ContextDev client = ContextDev( api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted ) response = client.news.search( search_by={ "entity": { "name": "xx", "type": "name", }, "type": "entity", }, ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.News.Search(context.TODO(), contextdev.NewsSearchParams{\n\t\tSearchBy: contextdev.NewsSearchParamsSearchBy{\n\t\t\tEntity: contextdev.NewsSearchParamsSearchByEntityUnion{\n\t\t\t\tOfName: &contextdev.NewsSearchParamsSearchByEntityName{\n\t\t\t\t\tName: \"xx\",\n\t\t\t\t},\n\t\t\t},\n\t\t\tType: \"entity\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Ruby source: >- require "context_dev" context_dev = ContextDev::Client.new(api_key: "My API Key") response = context_dev.news.search(search_by: {entity: {name: "xx", type: :name}, type: :entity}) puts(response) - lang: PHP source: >- news->search( searchBy: [ 'entity' => ['name' => 'xx', 'type' => 'name'], 'type' => 'entity' ], cursor: 'cursor', filterBy: [ 'articleLanguage' => ['ar'], 'articleType' => ['editorial'], 'date' => ['from' => 0, 'to' => 0], 'sourceCountry' => ['ae'], 'sourceDomain' => ['x'], ], limit: 1, sortBy: ['type' => 'relevance'], tags: ['production', 'team-alpha'], ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- context-dev news search \ --api-key 'My API Key' \ --search-by '{entity: {name: xx, type: name}, type: entity}' components: schemas: NewsSearchEntityByName: type: object properties: type: type: string enum: - name name: type: string minLength: 2 maxLength: 200 description: Company name. required: - type - name additionalProperties: false description: Identify the company by name. title: By Name NewsSearchEntityByDomain: type: object properties: type: type: string enum: - domain domain: type: string minLength: 1 maxLength: 253 description: Company website domain, such as apple.com. required: - type - domain additionalProperties: false description: Identify the company by website domain. title: By Domain NewsSearchEntityByTicker: type: object properties: type: type: string enum: - ticker ticker: type: string minLength: 1 maxLength: 20 pattern: ^[A-Za-z0-9.-]+$ description: Public-company ticker. exchange: type: string enum: - AMEX - AMS - AQS - ASX - ATH - BER - BME - BRU - BSE - BUD - BUE - BVC - CBOE - CNQ - CPH - DFM - DOH - DUB - DUS - DXE - EGX - FSX - HAM - HEL - HKSE - HOSE - ICE - IOB - IST - JKT - JNB - JPX - KLS - KOE - KSC - KUW - LIS - LSE - MCX - MEX - MIL - MUN - NASDAQ - NEO - NSE - NYSE - NZE - OSL - OTC - PAR - PNK - PRA - RIS - SAO - SAU - SES - SET - SGO - SHH - SHZ - SIX - STO - STU - TAI - TAL - TLV - TSX - TSXV - TWO - VIE - WSE - XETRA description: >- Stock exchange the ticker trades on, used to disambiguate tickers listed on multiple exchanges. required: - type - ticker additionalProperties: false description: Identify the company by stock ticker, optionally scoped to an exchange. title: By Ticker NewsSearchEntityByIsin: type: object properties: type: type: string enum: - isin isin: type: string pattern: ^[A-Za-z]{2}[A-Za-z0-9]{9}[0-9]$ description: International Securities Identification Number. required: - type - isin additionalProperties: false description: Identify the company by International Securities Identification Number. title: By ISIN RequestTags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 20 description: >- Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters. example: - production - team-alpha KeyMetadata: type: object properties: credits_consumed: type: integer description: The number of credits consumed by this request. credits_remaining: type: integer description: >- The number of credits remaining for your organization after this request. required: - credits_consumed - credits_remaining description: >- Metadata about the API key used for the request. Included in every response whenever a valid API key is provided, even when the response status is not 200. ErrorResponse: type: object properties: message: type: string description: Error message error_code: type: string enum: - INTERNAL_ERROR - VALID - NOT_FOUND - FORBIDDEN - USAGE_EXCEEDED - RATE_LIMITED - UNAUTHORIZED - DISABLED - PAID_PLAN_REQUIRED - INSUFFICIENT_PERMISSIONS - TIMEOUT_EXCEEDS_MAXIMUM - WEBSITE_ACCESS_ERROR - WEBSITE_BLOCKED - WEBSITE_NOT_FOUND - PDF_SKIPPED - PDF_IMAGES_ONLY - EXTERNAL_PROVIDER_ERROR - INPUT_VALIDATION_ERROR - ZDR_NOT_SUPPORTED - ZDR_NOT_ENABLED - FREE_EMAIL_DETECTED - DISPOSABLE_EMAIL_DETECTED - REQUEST_TIMEOUT - COLD_DOMAIN_TIMEOUT_TOO_LOW - UNSUPPORTED_CONTENT - CONTENT_TOO_LARGE - MONITOR_PAUSED - MONITOR_NO_WEBHOOK - COLLECTION_PAUSED - MONITOR_LIMIT_EXCEEDED - SEARCH_UNAVAILABLE - BATCH_LIMIT_EXCEEDED - BATCH_NOT_CANCELLABLE - BATCH_NOT_COMPLETED - IDEMPOTENCY_KEY_CONFLICT description: Error code indicating the type of error key_metadata: $ref: '#/components/schemas/KeyMetadata' headers: RateLimitLimit: description: >- Maximum requests allowed in the current fixed one-minute window. Returned when the authenticated API key has a per-minute rate limit. schema: type: integer minimum: 1 RateLimitRemaining: description: >- Requests remaining in the current fixed one-minute window. Returned when the authenticated API key has a per-minute rate limit. schema: type: integer minimum: 0 RateLimitReset: description: >- Unix timestamp in seconds when the current rate-limit window resets. Returned when the authenticated API key has a per-minute rate limit. schema: type: integer responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Unauthorized: description: Unauthorized headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' ````