Endpoints

On this page, we'll dive into the different endpoints you can use to retrieve financial news articles programmatically. We'll look at how to query articles using the finlight.me API.

Article model

The response article model contains all the information about an article, such as the link, title, publish date and source. It also contains a sentiment and its confidence about that.

Name
link
Type
string
Description
URL to the full article.
Name
source
Type
string
Description
Source website. E.g. www.reuters.com
Name
title
Type
string
Description
Title of the article.
Name
summary
Type
string
Description
Summary of the article if existing. Can be nullable.
Name
publishDate
Type
Date
Description
Publication date as ISO date.
Name
createdAt
Type
Date
Description
Date the article was first indexed by the finlight system, as ISO 8601 date string. Returned only when orderBy=createdAt is used.
Name
revisedDate
Type
Date | null
Description
Date the article was last revised after initial publication, as ISO 8601 date string. null when the article has never been revised. Returned when orderBy=revisedDate is used or includeUpdates is enabled via WebSocket/Webhook.
Name
isUpdate
Type
boolean
Description
true when this article payload is a re-delivery triggered by a post-publication revision. Only present when includeUpdates is enabled on a WebSocket or Webhook subscription.
Name
language
Type
string
Description
Language code in ISO 639-1. E.g. en | de | fr
Name
sentiment
Type
string
Description
Sentiment analysis result. Values can be positive | neutral |negative
Name
confidence
Type
string
Description
Confidence level of sentiment analysis from 0 to 1, returned as a stringified number (e.g. "0.95"). The TypeScript and Python clients parse it to a number for you.
Name
images
Type
string[]
Description
Array of image URLs from the article.
Name
countries
Type
string[]
Description
Array of country codes in ISO 3166-1 alpha-2 format representing the countries related to the article. E.g. ["US", "GB", "DE"]. Can be empty.
Name
categories
Type
string[]
Description
Array of article categories. Possible values: markets | economy | business | politics | geopolitics | regulation | technology | energy | commodities | crypto | health | climate | security. Can be empty.
Name
companies
Type
Company[]
Description
Array of companies that are mentioned in the article. Is only shown/available with specific subscription tier. Can be nullable.

Company model

The response company model contains information about a company that is mentioned in an article. It includes details like the company name, ticker symbol, industry, and more.

Name
companyId
Type
number
Description
Unique identifier for the company.
Name
confidence
Type
string
Description
Confidence level of the company identification, as a stringified number between 0 and 1 (e.g. "0.93"). The TypeScript and Python clients parse it to a number for you.
Name
country
Type
string
Description
Country where the company is based in ISO 3166-1 alpha-2 format. E.g. US | DE | GB
Name
exchange
Type
string
Description
Stock exchange where the company is listed.
Name
industry
Type
string
Description
Industry sector of the company. E.g. Biotechnology, Technology
Name
name
Type
string
Description
Full name of the company. E.g. Apple Inc.
Name
sector
Type
string
Description
Sector of the company. E.g. Technology | Health Care
Name
ticker
Type
string
Description
Stock ticker symbol of the company. E.g. AAPL | GOOGL
Name
isin
Type
string
Description
International Securities Identification Number (ISIN) of the company. E.g. US0378331005
Name
openfigi
Type
string
Description
OpenFIGI identifier for the company. E.g. BBG000B9XRY4
Name
primaryListing
Type
object
Description
Primary stock exchange listing information for the company.
Name
primaryListing.ticker
Type
string
Description
Primary ticker symbol on the main exchange.
Name
primaryListing.exchangeCode
Type
string
Description
Code of the primary exchange where the stock is listed.
Name
primaryListing.exchangeCountry
Type
string
Description
Country of the primary exchange where the stock is listed.
Name
isins
Type
string[]
Description
Array of International Securities Identification Numbers (ISINs) for the company.
Name
otherListings
Type
object[]
Description
Array of other stock exchange listings for the company.
Name
otherListings[].ticker
Type
string
Description
Ticker symbol on the alternative exchange.
Name
otherListings[].exchangeCode
Type
string
Description
Code of the alternative exchange where the stock is listed.
Name
otherListings[].exchangeCountry
Type
string
Description
Country of the alternative exchange where the stock is listed.

POST/v2/articles

Fetch articles

Retrieve article information, including detailed analysis, companies and more. Please note that some fields require a specific subscription tier to access.

Optional BODY parameters

Because this endpoint uses a POST request, you can pass parameters in the body of the request. This allows for more complex queries and filtering options.

Name
query
Type
string
Description
Search query to find relevant articles with simple or advanced filters. Advanced queries
Name
sources
Type
string[]
Description
Simple filter for single or multiple sources (String Array). See "Get all sources" endpoint for valid values. Supports wildcard "*" to include all sources.
Name
optInSources
Type
string[]
Description
Additional sources to include on top of your default source set (String Array). See "Get all sources" endpoint for valid values.
Name
excludeSources
Type
string[]
Description
Excludes single or multiple sources (String Array). See "Get all sources" endpoint for valid values.
Name
tickers
Type
string[]
Description
Filter by stock ticker symbols (String Array). This will return articles that mention these tickers. Supports wildcard "*" to include all tickers.
Name
countries
Type
string[]
Description
Filter by the countries an article is about, using ISO 3166-1 alpha-2 country codes (String Array). E.g. ["US", "GB", "DE"]. This matches the article's countries field, not the publisher's country, a company's domicile, or a listing market.
Name
categories
Type
string[]
Description
Filter by article category (String Array). Possible values: markets, economy, business, politics, geopolitics, regulation, technology, energy, commodities, crypto, health, climate, security.
Name
includeEntities
Type
boolean
Description
Includes the companies mentioned in the article. Requires a specific subscription tier.
Name
from
Type
string
Description
Start date in YYYY-MM-DD format or ISO date string.
Name
to
Type
string
Description
End date in YYYY-MM-DD format or ISO date string.
Name
language
Type
string
Description
Filter by language (ISO 639-1). Defaults to en, which returns English only and excludes other languages — see Language & Coverage.
Name
orderBy
Type
string
Description
Order by ("publishDate", "createdAt", or "revisedDate") - default "publishDate". publishDate is the article's publication date from the source. createdAt is when the article was first indexed by finlight. revisedDate sorts by the most recent revision date (articles never revised appear last). Keep in mind that some sources publish articles with past publication dates.
Name
order
Type
string
Description
Sort order ("ASC" or "DESC") - default "DESC".
Name
pageSize
Type
number
Description
Number of results per page (1-100).
Name
page
Type
number
Description
Page number.

Request

POST

/v2/articles

curl -X POST 'https://api.finlight.me/v2/articles' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{ "query": "Nvidia", "countries": ["US", "GB"] }'

Response

{
  "status": "ok",
  "page": 1,
  "pageSize": 20,
  "articles": [
    {
      "link": "https://www.example.com/article1",
      "source": "www.example.com",
      "title": "Stock Market Hits New Highs",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": "0.95",
      "images": [
                  "https://www.example.com/image1.jpg",
                  "https://www.example.com/image2.jpg"
                ],
      "countries": ["US"],
      "categories": ["markets", "technology"],
      "companies": [
                {
                    "companyId": 41494,
                    "confidence": "0.9335401058197021",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Biotechnology: Pharmaceutical Preparations",
                    "name": "Summit Therapeutics Inc. Common Stock",
                    "sector": "Health Care",
                    "ticker": "SMMT",
                    "isin": "US86627T1088",
                    "openfigi": "BBG01PH11VP5",
                    "primaryListing": {
                        "ticker": "SMMT",
                        "exchangeCode": "XNAS",
                        "exchangeCountry": "US"
                    },
                    "isins": ["US86627T1088", "US86627T2088"],
                    "otherListings": [
                        {
                            "ticker": "SMMT.L",
                            "exchangeCode": "XLON",
                            "exchangeCountry": "GB"
                        }
                    ]
                },
                ...
              ]
    },
    // ...
  ]
}

GET/v2/articles/by-link

Fetch article by link

Retrieve a single article by its URL. Returns the full article data with sentiment analysis and optionally includes content and company entities.

Required query parameters

Name
link
Type
string
Description
The URL of the article to fetch.

Optional query parameters

Name
includeContent
Type
boolean
Description
(Deprecated) Include the full article content in the response.
Name
includeEntities
Type
boolean
Description
Include the companies mentioned in the article. Requires a specific subscription tier.

Request

GET

/v2/articles/by-link

curl -X GET 'https://api.finlight.me/v2/articles/by-link?link=https%3A%2F%2Fwww.somepage.com%2Ftechnology%2Fexample-article&includeContent=true&includeEntities=true' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'

Response

{
  "status": "ok",
  "article": {
      "link": "https://www.somepage.com/technology/example-article",
      "source": "www.reuters.com",
      "title": "Nvidia Announces New GPU Architecture",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": "0.95",
      "content": "Full article content here...",
      "images": [
                  "https://www.example.com/image1.jpg"
                ],
      "countries": ["US"],
      "categories": ["technology"],
      "companies": [
                {
                    "companyId": 4157,
                    "confidence": "0.97",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Semiconductors",
                    "name": "NVIDIA Corporation",
                    "sector": "Technology",
                    "ticker": "NVDA",
                    "isin": "US67066G1040",
                    "openfigi": "BBG000BBJQV0"
                }
              ]
  }
}

GET/v2/sources

Get all sources

Retrieve a list of all currently supported article sources.

Note: The sources are scraped on a best-effort basis and may change in the future.

Response

A JSON array of source objects. Example:

Name
array
Type
Source[]
Description
Array of news sources.

Source model

The response source model contains information about a news source, including its domain, origin country, languages, and whether it is a default source.

Name
domain
Type
string
Description
Domain of the source website.
Name
isDefaultSource
Type
boolean
Description
Indicates if this source is served by default (without having to include it in sources).
Name
originCountry
Type
string
Description
Origin country of the source in ISO 3166-1 alpha-2 format. E.g. US | GB | DE. Can be empty.
Name
languages
Type
string[]
Description
Languages the source publishes in, as ISO 639-1 codes, primary (most-common) first. E.g. ["en"].
Name
isCustomSource
Type
boolean
Description
Present and true only when this source is a custom source enabled for your subscription.
Name
isContentAvailable
Type
boolean
Description
(Deprecated) Whether scraped content is available for this source. Only present on plans with full article content access.

Request

GET

/v2/sources

curl -X GET 'https://api.finlight.me/v2/sources' \
  -H 'X-API-KEY: YOUR_API_KEY'

Response

[
  {
    "domain": "www.yahoo.com",
    "isDefaultSource": true,
    "originCountry": "US",
    "languages": ["en"]
  },
  {
    "domain": "seekingalpha.com",
    "isDefaultSource": true,
    "originCountry": "US",
    "languages": ["en"]
  },
  // ...
]