introduction

If you’re building a trading agent, a research tool, a compliance system, or any application that consumes financial content at scale, you need one data infrastructure API that covers everything and affordably so: real-time news, sentiment scores, investor relations documents, and insider transactions. Not four separate integrations, not stale data, not token-burning LLMs, and not vendors that lock you into inflexible enterprise contracts.

The CityFALCON API delivers all of this through a single, consistent interface, aggregating content from over 10,000 sources across more than 50 languages, with proprietary sentiment analysis, NLU tagging, and the CityFALCON Score for relevance ranking. It’s the same infrastructure trusted by eToro, BNP Paribas, StockTwits, and StoneX.

This guide walks through exactly how to use the API, with real endpoint examples for each content type and practical filtering techniques. By the end, you will know how to pull financial news filtered by relevance, retrieve sentiment (per-item and timeseries), access investor relations documents like earnings and press releases, get insider transaction data, and combine these into complete workflows.

 

Why the CityFALCON API

Before we dive into the endpoints, a quick note on what makes this API different from others in the market:

  • Breadth in one place. News, sentiment, IR documents, and insider transactions all use the same identifier format and share consistent metadata. No stitching together four vendors.
  • Structured and pre-scored. Every story is tagged with sentiment, entities, and a proprietary CityFALCON Score for relevance. You skip the expensive step of running raw text through an LLM to figure out what’s relevant.
  • Truly global. 50+ languages, 10,000+ sources, covering global markets around the clock.
  • Flexible consumption. Direct API access for enterprises or high-volume applications, plus per-call access via Apiosk for AI agents and developers who want pay-as-you-go.

Now, the how-to.

 

Authentication

All CityFALCON API requests use a single authentication method: an access_token query parameter passed with every request. Very simple with no headers to configure, no OAuth flows, no session tokens. 
Example:

https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY

Simply append access_token=YOUR_API_KEY to any endpoint URL. Missing or invalid tokens return a 401 response. Test tokens are available for interested enterprises. See plans on our pricing page, then contact us with the form at the bottom of the page. 

 

How to Get Financial News via API

Financial news is retrieved from the /stories endpoint. Each story returns at least headline, source’s description, asset tags, CityFALCON Score, source information, and optionally sentiment and NLU tags, so you have everything you need to make decisions without further processing.

 

Retrieve news for a ticker

Retrieve stories about specific companies using full ticker format ([ticker]_[country_code]):

GEThttps://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifier_type=full_tickers&identifiers=AAPL_US,MSFT_US,GOOG_US

Make sure to use the “full tickers”, that is the ticker plus the country code of the listing, which will disambiguate companies.

 

Filter news by language

Restrict results to specific languages using ISO codes:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&languages=en,de

Leave the parameter blank to get content in all 50+ available languages, essential for agents operating across global markets where a Japanese story at 3am Tokyo time can be just as market-moving as a New York headline.

 

Filter news by publisher category

Focus on top-tier publications only:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&categories=mp

Category slugs:

  • mp — major news publications
  • op — other news publications
  • r — research publications

“Major publications” are about 200 that human analysts have determined to be the most important, influential, or reliable.

 

Filter news by relevance (CityFALCON Score)

Every story is scored 0-100 for relevance to the queried entity. This is one of the most powerful filtering tools in the API and something most competing providers don’t offer. Filter out low-relevance noise by setting a minimum score:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifiers=AAPL_US&min_cityfalcon_score=50

Setting min_cityfalcon_score=50 typically returns only substantive news about the target, excluding passing mentions. For humans, this makes reading results much easier and more impactful, both for professional users or general public end users. For any agent-related applications looking at thousands of tickers, this filter is the difference between a manageable feed and a cost-prohibitive firehose.

Note that smaller companies or those with little news volume may end up with lower scores (in part because one of the inputs to the CF score is the authority of the publishing source). It is best to maintain a fallback process to reduce the CF score in steps.

 

Filter by country

Get news relevant to specific countries:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&country_codes=US,GB,JP

 

Filter by defined events

Filter for specific corporate events like buybacks or analyst ratings, no LLM parsing required:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&events=stock-buyback,analyst-sell-rating

See our help centre for the full list of events.

 

Get news with sentiment attached

Return the sentiment score alongside each story:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifiers=AAPL_US&with_sentiment=true

For finer control, get sentiment broken down by entity within each story (e.g. Apple mentioned positively within an article that also references Samsung negatively):

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifiers=AAPL_US&with_sentiments_by_entities=true

 

Get news with NLU labels attached

CityFALCON automatically tags all incoming news content via its proprietary taxonomy. These tags are available to clients, too, which is particularly useful for anyone pulling large amounts of data and who needs to index inside their own applications.

Get these entity-recognition labels with a single parameter:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifiers=AAPL_US&with_nlu_labels=true

 

How to Get Sentiment Timeseries via API

The dedicated /services/sentiment endpoint returns aggregated sentiment for specific entities over a defined time period. Instead of pulling raw stories and computing sentiment yourself (expensive and technically burdensome if you do it yourself), let CityFALCON do it behind the API and pull it all at once.

 

Get sentiment for a company

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifier_type=full_tickers&identifiers=AAPL_US&period=d1

 

Get sentiment for multiple entities at once

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifiers=AAPL_US,MSFT_US,GOOG_US&period=h8

Supported time periods:

  • m5 — 5 minutes
  • m15 — 15 minutes
  • h1 — 1 hour
  • h8 — 8 hours
  • d1 — 1 day
  • w1 — 1 week
  • mth1 — 1 month

 

Get sentiment for a country

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifier_type=country_codes&identifiers=US,JP&period=w1

 

Include averages and statistics

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifiers=AAPL_US&period=d1&average_for_period=true&statistics_for_period=true

This includes story counts for each bucket (very positive, positive, etc.).

 

How to Get Investor Relations Documents via API

Investor relations content, including earnings materials, press releases, and financial statements, is retrieved from the /investor_relations endpoint. IR data is critical for research and compliance, and it’s often the most useful signal for company-specific decisions.

 

Get IR documents for a company

GET https://api.cityfalcon.com/v0.2/investor_relations?access_token=YOUR_API_KEY&identifiers=AAPL_US

 

Filter IR documents by type

GET https://api.cityfalcon.com/v0.2/investor_relations?access_token=YOUR_API_KEY&identifiers=AAPL_US&type=Earnings,Press Release

Supported types include:

  • Gains
  • Press Release
  • Financial Statements
  • Autres

 

Filter IR documents by date range

Retrieve documents between two dates (YYYY-MM-DD format):

GET https://api.cityfalcon.com/v0.2/investor_relations?access_token=YOUR_API_KEY&identifiers=AAPL_US&start_date=2026-01-01&end_date=2026-03-31\

Note: API queries are limited to the most recent 30 days. For historical analysis going further back, CityFALCON provides downloadable CSV datasets that can extend across years of coverage.

 

How to Get Insider Transactions via API

Insider transactions from corporate officers and major shareholders often provide some of the strongest early signals about a company’s trajectory. The /insider_transactions endpoint delivers them in structured, filtered form.

Beyond the basic data, there is also an informative/uninformative switch to narrow down actionable data or generally pull compliance-related information.

Note: Insider tx only covers US companies and officers that are required to file the SEC Form 4.

 

Get insider transactions for a company

GET https://api.cityfalcon.com/v0.2/insider_transactions?access_token=YOUR_API_KEY&identifiers=AAPL_US

 

Filter insider transactions by type

Filter for buys and sells only:

GET https://api.cityfalcon.com/v0.2/insider_transactions?access_token=YOUR_API_KEY&identifiers=AAPL_US&transaction_type=buy,sell

Supported transaction types:

  • buy
  • sell
  • gift
  • option exercised
  • autre

 

Filter for informative transactions only

Not every insider transaction is meaningful. CityFALCON flags each as informative or uninformative based on how the form has been filled out by the officer/filer, saving you from noise like automatic vesting or programmatic option exercises:

GET https://api.cityfalcon.com/v0.2/insider_transactions?access_token=YOUR_API_KEY&identifiers=AAPL_US&info_type=informative

 

Filter insider transactions by date range

Insider transaction dates use UNIX timestamps:

GET https://api.cityfalcon.com/v0.2/insider_transactions?access_token=YOUR_API_KEY&identifiers=AAPL_US&start_date=1717200000&end_date=1719878400

 

How to Query Financial Content by DCSC Sectors

CityFALCON’s Dynamic Company Sector Classification (DCSC) system covers over 1,500 sectors across 4 levels. DCSC works across the /stories et /services/sentiment endpoints, so you can pull news, sentiment, and relevance scores for entire sectors, not just individual tickers.

 

Get news for a DCSC sector

Retrieve stories tagged to a specific sector using the dcsc_sectors parameter on the /stories endpoint:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&dcsc_sectors=semiconductors&time_filter=d1

 

Refine by DCSC sector level

DCSC is a hierarchical classification. Use dcsc_sector_level to narrow the query to a specific level of granularity:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&dcsc_sectors=semiconductors&dcsc_sector_level=4

 

Combine DCSC sectors with CityFALCON Score

Filter for only the most relevant sector news by combining the DCSC sector filter with a minimum relevance score:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&dcsc_sectors=semiconductors&min_cityfalcon_score=70&time_filter=d1

This returns only high-relevance news across the entire semiconductor sector, replacing what would otherwise be dozens of individual ticker queries.

 

Get sentiment for a DCSC sector

Track aggregated sentiment for a specific sector:

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifier_type=dcsc_sectors&identifiers=semiconductors&period=d1

 

Get sentiment for multiple DCSC sectors at once

GET https://api.cityfalcon.com/v0.2/services/sentiment?access_token=YOUR_API_KEY&identifier_type=dcsc_sectors&identifiers=semiconductors,electric-vehicles,solar-energy&period=w1

DCSC sector queries are particularly useful for macro and thematic strategies, sector rotation analysis, and any use case where tracking individual tickers is too narrow.

 

How to Filter Financial Content at Scale

The real power of the CityFALCON API comes from combining filters in a single request. Instead of pulling everything and filtering client-side (expensive at scale), let the API do the work. Here are practical patterns for common use cases.

 

High-signal news for a portfolio

Get only high-relevance news for a portfolio of tickers, in English, from major publications, from the past 8 hours, with sentiment attached:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifier_type=full_tickers&identifiers=AAPL_US,MSFT_US,NVDA_US,AMZN_US&languages=en&categories=mp&time_filter=h8&with_nlu_labels=true&min_cityfalcon_score=50&with_sentiment=true&with_nlu_labels=true

That’s one API call that returns data from a vast array of data sources, with sentiment and relevance metrics pre-calculated, fully-labeled with tags, in a machine-readable format and structure, plus basic metadata. Internally building all of that, and then processing the flood of results, is no small or economical task. Our API makes it straightforward and highly affordable.

 

Multilingual monitoring for a global company

Get all news mentioning a company across all languages from the past hour, ideal for agents monitoring companies with global operations:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifier_type=full_tickers&identifiers=TSLA_US&time_filter=h1

 

Event-driven filtering

Detect specific corporate events across your watchlist without post-processing:

GET https://api.cityfalcon.com/v0.2/stories?access_token=YOUR_API_KEY&identifiers=AAPL_US,MSFT_US,GOOG_US&events=stock-buyback&time_filter=w1

 

Combining Content Types for Full Company Awareness

Most serious use cases require multiple content types combined. Here’s how one might build a complete view of a single company using the CityFALCON API:

Step 1 – Get high-relevance news with sentiment:

GET /stories?identifiers=AAPL_US&min_cityfalcon_score=50&with_sentiment=true&time_filter=d1

Step 2 – Get aggregate sentiment for context:

GET /services/sentiment?identifiers=AAPL_US&period=w1&average_for_period=true

Step 3 – Get recent IR documents:

GET /investor_relations?identifiers=AAPL_US&type=Earnings,Press Release

Step 4 – Get insider transactions for the same period:

GET /insider_transactions?identifiers=AAPL_US&info_type=informative&transaction_type=buy,sell

Four API calls, one company, complete picture. Try building that against four separate vendors or attempting to build the entire infrastructure internally.

 

Best Practices

Use full tickers with country codes. Le [ticker]_[country] format (e.g. AAPL_US, GOOG_US) is unambiguous and works consistently across all endpoints. The same company listed in two countries has two different full tickers. As an example, AA_GB et AA_US sont ne pas the same company (British-American Tobacco and American Airlines, respectively).

Filter with CityFALCON Score. Setting min_cityfalcon_score=50 cuts out the noise of passing mentions and returns only substantive news. This dramatically reduces the volume you need to process and is one of the biggest cost savings available. Note that smaller companies may not have enough news with high scores, so it is useful to have a fallback and reduces the score in steps, then using your minimum score based on your particular use case and basket of companies, assets, and/or topics.

Match time periods to use case. Short periods (m5, m15, h1) are ideal for real-time trading applications. Longer periods (d1, w1, mth1) work better for research, backtesting, and trend tracking.

Combine filters aggressively. Every filter you apply reduces the response payload and shortens processing time. Filter by ticker, category, language, and score in a single request rather than post-processing.

Note the 30-day API window. All endpoints are limited to the most recent 30 days. For historical analysis, CityFALCON provides downloadable CSV datasets. Get in contact to discuss pricing and datasets available.

 

Getting Started

The CityFALCON API is trusted by eToro, BNP Paribas, and StoneX, and available directly at cityfalcon.ai. For AI agents and developers who prefer pay-per-call access, CityFALCON is also listed on Proxygate and Apiosk, with no subscription required (not recommended for any high-volume cases as the per-call cost becomes more expensive than an enterprise contract).

Whether you’re a broker, a bank, a trading house, a research platform, a compliance system, or any application that needs structured financial content at scale, the CityFALCON API provides the news, sentiment, investor relations documents, and insider transactions you need through a single, consistent interface.

Browse plans and costs, then contact us to get started!