Advanced Filtering: Precise Queries with the finlight API

A broad news feed is noise. The value is in getting exactly the stories you care about. finlight gives you two ways to do that, and they work together:

1. Structured filters for the common cases (tickers, countries, categories, sources, dates).
2. A query language in the query field for boolean logic and full-text matching.

This guide covers both, using POST /v2/articles. If you haven't made a first call yet, start with the Quick Start guide.

Structured filters

These are the parameters you'll reach for most often:

• tickers — companies, e.g. ["AAPL", "NVDA"]
• countries — ISO 3166-1 alpha-2 codes, e.g. ["US", "GB"]
• categories — one or more of the 13 categories, e.g. ["markets", "regulation"]
• sources / excludeSources / optInSources — include, exclude, or opt in to specific outlets
• from / to — date range, YYYY-MM-DD or ISO 8601
• order (ASC / DESC) and orderBy (publishDate, createdAt, revisedDate)

A simple structured request:

curl -X POST https://api.finlight.me/v2/articles \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["AAPL", "NVDA"],
    "categories": ["markets"],
    "from": "2026-01-01",
    "pageSize": 50
  }'

The query language

When you need boolean logic or text matching, use the query field. It supports field filters, boolean operators, grouping, exact phrases, and wildcards.

Supported fields

Operators

• AND / OR / NOT to combine terms.
• Parentheses ( ) to group, e.g. (ticker:AAPL OR ticker:NVDA).
• Quotes " " for an exact phrase, e.g. "interest rates".
• Wildcards * on ticker, source, and exchange, e.g. ticker:BRK*.
• + / - to require or exclude a term, e.g. +ticker:AAPL -category:crypto.

Putting it together

Find earnings stories about Apple or Nvidia, but not from a specific source:

(ticker:AAPL OR ticker:NVDA) AND "earnings" AND NOT source:www.example.com

Structured filters and the query string are combined (AND-ed together), so you can mix them. For example, send query for the boolean logic and categories / from as structured filters:

// TypeScript
import { FinlightApi } from 'finlight-client';

const client = new FinlightApi({ apiKey: 'YOUR_API_KEY' });

const response = await client.articles.fetchArticles({
  query: '(ticker:AAPL OR ticker:NVDA) AND "earnings"',
  categories: ['markets'],
  from: '2026-01-01',
  pageSize: 50,
});

# Python
from finlight_client import FinlightApi, ApiConfig
from finlight_client.models import GetArticlesParams

client = FinlightApi(config=ApiConfig(api_key="YOUR_API_KEY"))

params = GetArticlesParams(
    query='(ticker:AAPL OR ticker:NVDA) AND "earnings"',
    categories=["markets"],
    from_="2026-01-01",
    pageSize=50,
)
response = client.articles.fetch_articles(params)

Pagination and deep history

Use page and pageSize (up to 100 per page) to page through results. There is one rule to know: the offset (page * pageSize) is capped at 10,000. To go deeper into history, don't keep increasing page — narrow the window with from and to instead and page within each window. This keeps queries fast and lets you walk through any amount of history.

Where to go next

• Tickers & Exchanges Done Right — filter precisely for dual-listed companies.
• Global News by Country & Category.
• Full documentation.

Get your free API key →