DEV Community: Oleksyj Mokrousov

Improve AI Output with a News Feed: Ground LLM Answers in Live Coverage

Oleksyj Mokrousov — Fri, 21 Aug 2026 10:25:48 +0000

Why LLM answers drift without a live news feed

Teams ship chatbots, research agents, and support copilots that sound confident on last week’s events - then invent partnerships, mix up CEOs, or cite outlets that never ran the story. Model weights are stale. A generic web scrape is noisy. What fixes AI output for current events is a news feed for AI: structured, filterable coverage you retrieve first, then pass into the prompt as evidence.

Fintech and payments desks see this clearly. A model asked “what is Stripe doing in sponsorships?” without a feed will improvise. The same question with a grounded AI context pack - recent articles and story clusters pinned to the company - stays on published facts.

Developers usually ask:

Why does raw LLM output fail on live news without a feed?

How do you build a filtered news feed as LLM context?

How do you pack article and story fields into prompts without drowning the model?

When should you use Articles, Stories, Search Summarizer, or MCP?

Which filters keep a company or executive context pack clean?

The sections below answer each in order.

Try it live: Articles sandbox · Read the docs: Entities · Compare plans: API pricing

Why raw LLM output fails on live news

An LLM without retrieval answers from training cutoffs and pattern completion. That fails when the user needs live news for AI:

Stale knowledge. Product launches, partnerships, and regulatory moves after the cutoff never appear - or appear as confident fiction.

Homonym collisions. “Stripe” and “Collison” hit sports, entertainment, and unrelated brands unless the feed uses entity IDs.

No citations. Fluent prose without publisher, date, and title makes compliance and desk review impossible.

Unscoped volume. Dumping the open web into the context window adds forums, reprints, and off-topic inflation pieces that dilute the answer.

A RAG news feed (retrieve → pack → generate) keeps the model honest: the corpus is your filtered news data for AI, not the entire internet.

How to build a filtered news feed as LLM context

Treat Perigon Articles (/v1/all) as the retrieval layer for LLM context news. Resolve the company once, then poll a tight window.

Worked example - payments company watch:

Role	Prefer	Value
Stripe (payments)	companyId	9c0e5ff08b87453b8f6fa108a73b57b5
Stripe (domain pin)	companyDomain	stripe.com when you want domain-linked hits
Patrick Collison (CEO)	personWikidataId	Q7146257

On Articles, pass companyId set to 9c0e5ff08b87453b8f6fa108a73b57b5, set sortBy to date, and bound from / to (or addDateFrom for incremental polls). Keep size small for a context pack - often 5 to 15 articles - so the model can read titles and summaries without truncating mid-sentence.

People search for “Patrick Collison” can return basketball and entertainment Collisons. Keep personWikidataId Q7146257 when the lane is leadership commentary, not the company-wide feed. Deep entity param theory lives in the Company News API guide; this page owns the improve AI output packing pattern.

For narrative heat without reprint spam, run the same companyId on Stories (/v1/stories/all). Coverage often looks like a sponsorship or partnership cluster - for example a Stripe worldwide partner announcement spanning multiple outlets under one story name - which compresses better into a prompt than eleven near-duplicate headlines.

How to pack fields into prompts without drowning the model

Retrieval is not enough. Ground LLM quality depends on what you paste and what you instruct.

Context pack recipe (per hit):

Title

Publisher domain

Publication date

Short summary or key points (not full body by default)

Optional company / person names already on the record

Prompt scaffolding:

Instruct the model to answer only from the packed items.

Require citations as title + domain + date.

Cap length (bullets or a short brief).

Say what to do when the pack is empty: admit gaps, do not invent.

Size discipline: Prefer recent, entity-pinned hits over a large unsorted dump. Default article order without sortBy date can surface old or off-beat pages first - useless for AI with live news.

Raise quality with sourceGroup (for example top100) and excludeLabel Opinion, Paid News, or Press Release when you want third-party reporting only.

Search Summarizer can turn the same filters into one model-written briefing when the deliverable is a digest, not a custom agent reply - see the AI News Summaries guide. Keep this article on feeding your LLM.

When to use Articles, Stories, Summarizer, or MCP

Job	Prefer	Why
Custom chatbot / agent answers with citations	Articles → your LLM	You own the prompt, tools, and UX
Fewer reprints in the context window	Stories first, then sample articles	One narrative per cluster
One leadership-ready digest, Perigon-written	Search Summarizer	Prompted briefing of the matched set
IDE / assistant tool access without custom retrieval code	MCP	Agent tools over the same news graph - see real-time news for AI agents

News feed grounding and Summarizer both start from filtered search. Grounding keeps generation in your stack; Summarizer returns the briefing as the API response.

Which filters keep a company context pack clean

Group parameters by the grounding job:

Use case	Params to teach first
Pin the company	companyId, optional companyDomain
Pin an executive	personWikidataId
Freshness for RAG	from / to, addDateFrom, sortBy date
Context window budget	size, page
Publisher quality	source, sourceGroup
Cut non-reporting noise	excludeLabel
Optional topic fence	category, topic, short q

Start with companyId for Stripe-scale watches. Add personWikidataId only for CEO interview or leadership lanes - company volume and person volume differ sharply (see facts below). Stack excludeLabel and a trusted sourceGroup before you grow size.

What results look like for grounding

Each Articles hit gives the fields most agents need: title, url (when your product deep-links), pubDate, publisher domain, summary, and linked companies or people. You map those into the context block; you do not need full HTML.

Stories return a cluster name, summary, article count, and update time - enough to tell the model “this is one partnership narrative with N outlets,” then attach one or two representative article rows if citations matter.

Pattern check (evergreen shape, not a permanent newsjack): a recent Stripe-linked story can look like a multi-outlet sports-partnership announcement (Ryder Cup worldwide partner framing) with on the order of ten related articles under one cluster - ideal Stories-first packing when reprints would otherwise fill the window.

Use cases

Support and success copilots

Retrieve the last week of companyId coverage before the model answers “what changed for this vendor?” Pack titles and domains so agents cite press, not rumor.

Research and analyst agents

Run parallel packs: company feed vs personWikidataId leadership feed. Compare volumes, then ask the model for a short memo with separate citation lists.

Product features that “know the news”

Ship a “sources used” panel from the same pack you sent to the model - title, domain, date - so users can audit grounded AI answers.

When to ground vs summarize vs monitor

Goal	Path
Improve answers inside your LLM app	Articles/Stories → context pack → your model
One digest without building a packer	Search Summarizer
Always-on desk briefing product	Signals on perigon.io/home (product path; not this API recipe)
Entity filter depth	Company News API guide

Compose the feed with other filters

Entity pins set who. Dates and sortBy set when. sourceGroup and excludeLabel set quality. Optional q (partnership, pricing, regulation) narrows event language without replacing the allowlist. Poll with addDateFrom so each agent turn only spends tokens on new hits.

Stripe grounding at a glance

Payments coverage is continuous: product, partnerships, regulation, and executive commentary move on different cadences. Entity pins keep a news feed for AI on the company instead of every “stripe” metaphor in sports or design.

What that looks like in the index (30 days, pubDate 2026-06-23 to 2026-07-23): about 11,000 articles linked to Stripe (companyId 9c0e5ff08b87453b8f6fa108a73b57b5).

Leadership is a thinner lane: about 150 articles for Patrick Collison (personWikidataId Q7146257) in the same window. Pack company and CEO feeds separately so a support copilot does not drown in executive profile pieces - or miss a partnership cluster when it only watched the person ID.

Key takeaways

Improve AI output on current events by retrieving a filtered news feed before generation - not by hoping the model remembers.

Pin entities (companyId, personWikidataId), sort by date, and keep size small enough for reliable citations.

Pack title, domain, date, and short summary; instruct the model to stay inside the pack.

Use Stories to compress reprints; use Search Summarizer or MCP when you want a Perigon briefing or agent tools instead of a custom packer.

Separate company-scale and executive-scale watches - volumes differ, and mixed packs confuse the model.

Get started: Entities · API reference · Articles sandbox · API pricing

Competitor News Monitoring with the News API: Track Rival Companies and Political Rivals

Oleksyj Mokrousov — Fri, 21 Aug 2026 10:16:47 +0000

Why competitor news monitoring fails on keywords alone

Competitor news monitoring is not searching a rival’s name every morning. Company launches, defense awards, and earnings hit the wire in the same week as political rivals fight for headline share. Keyword q alone cannot keep those lanes clean.

Search Lockheed, RTX, or defense and you also match namesakes, sports metaphors, and consumer brands. Search Trump or Biden and you also match family members, entertainment rows, and caption noise. The rivals you mean stay hard to compare side by side.

Try it live: Articles sandbox · Docs: Entities · Plans: API pricing

This guide answers:

What is competitor news monitoring on a news API?

How do you build a rival company watchlist with entities?

How do you compare political rivals like Trump and Biden?

How do you compare coverage volume across competitors?

How do you keep earned coverage vs press-release noise?

Which recipes fit company CI vs political CI vs Stories?

Param encyclopedias live in the Company News API guide and Entities docs. Product briefings belong on Monitor Defense Industry News or Monitor US Politics News. This page owns the API competitive-intelligence workflow - companies and people as rivals.

What competitor news monitoring means on a news API

On Perigon, competitors are whoever you need to compare in coverage - primes, brands, or political figures. The workflow is the same shape:

1) Pick a stable rival set.

2) Resolve each rival to a durable ID (companyId / companySymbol, or personWikidataId).

3) Run the same Articles (/v1/all) recipe once per rival in one date window.

4) Compare volume and themes; optionally open Stories when one move reprints everywhere.

You filter who was linked on the article. You do not scrape competitor websites. You do not call another vendor’s news API.

Rival type	Resolve with	Filter on Articles / Stories
Company / brand	Companies API	companySymbol, companyId, companyDomain
Political figure	People API	personWikidataId (prefer) or personName
Event language	-	Optional q (award, earnings, debate)
Earned-only	-	excludeLabel
Reprint collapse	-	Stories with the same entity fence

How to build a rival company watchlist with entities

Resolve each rival once on the Companies API (/v1/companies/all). Prefer the parent listed company and a primary companySymbol. Skip subsidiaries and namesakes unless that unit is the desk’s target.

Example A - Defense primes as rivals

Live Companies lookup (not a Signals tutorial):

Rival (parent)	Prefer	companyId	Symbol
Lockheed Martin Corporation	Parent - not Rémy Martin / Martin Professional	2fa32c247a6f4d83be3c163cc685691b	LMT
RTX (US aerospace / defense)	companySymbol RTX - name “RTX” can return Danish RTX A/S	(use symbol; skip f531cda3de2c47128cee041eb5327d83)	RTX
Northrop Grumman Corporation	Parent - not Sperry Marine alone	7ba58a4019cf48afb56c710b0e8d0ef2	NOC
The Boeing Company	Parent - not Boeing Store / BECU	c825868b46614e598257013cf9f39c03	BA
General Dynamics Corporation	Parent - not Mission / Land Systems / Electric Boat alone	a61d0b7101cf411ebcfbacd479586be7	GD

Apply it

Store id + symbol in config.

Pass companySymbol set to LMT (or Lockheed’s companyId) on Articles.

Repeat for RTX, NOC, BA, and GD.

Add q only for move type (award, earnings, partnership).

Example recipes (defense)

CI question	Recipe
All Lockheed-linked news	companySymbol=LMT, sort by date
Lockheed awards only	companySymbol=LMT + q=award OR contract
RTX vs LMT volume this month	Two queries, same from/to, compare numResults
Boeing commercial + defense noise cut	companySymbol=BA + excludeLabel Non-news
GD shipbuilding desk	companyId for General Dynamics Corporation (avoid Electric Boat-only unless needed)
Five-prime morning digest	Five parallel queries → Summarizer per rival

Name collisions are the failure mode. “Martin” or “RTX” without entities are research strings, not keys. Refresh IDs when tickers or structure change.

Example B - Brand and sponsor rivals (pattern)

The same pattern works outside defense. Resolve each brand on Companies, then run parallel companySymbol or companyId watches - for example Nike (NKE) vs a sportsbook or apparel rival on your book. Keep one query per brand in the same window. Domain filters (companyDomain) help when the rival is private or the ticker is ambiguous. Full ticker/domain cookbook stays in the Company News guide.

How to compare political rivals like Trump and Biden

Political competitors are people, not tickers. Resolve each on the People API (/v1/people/all), store personWikidataId, and run parallel Articles queries. Deeper person methodology lives in the political rival mentions guide - the worked pair below is the CI example for this page.

Example C - Trump vs Biden (live People lookup)

Rival	Prefer this row	personWikidataId
Donald Trump	US politician / President row - not Donald Trump Jr.	Q22686
Joe Biden	46th President row - not Hunter Biden, Ashley Biden, or singer “Joe”	Q6279

People search for “Donald Trump” also returns Melania, Ivana, and Ivanka. “Joe Biden” also returns Hunter, Ashley, Valerie Biden Owens, and unrelated Joe rows. Pin Wikidata IDs or the wrong human enters the feed.

Apply the pair

Feed A: personWikidataId set to Q22686.

Feed B: personWikidataId set to Q6279.

Same from / to window for both.

Optional fence: category set to Politics and sourceCountry set to us.

Optional q: debate, executive order, campaign - event language only.

Political volume (30 days)

pubDate 2026-06-23 through 2026-07-23:

Filter	About how many articles
Trump Q22686	~980,000
Biden Q6279	~75,000
Trump + Politics + US sources	~290,000
Biden + Politics + US sources	~38,000

Round large totals; very large person feeds can sit near caps - prefer relative wording. In this window Trump-linked volume sat roughly an order of magnitude above Biden overall, and still several times higher inside the US Politics fence. Use that as triage for coverage heat - not as an election scoreboard.

Political recipe table

CI question	Recipe
Open Trump mention firehose	personWikidataId=Q22686
Open Biden mention firehose	personWikidataId=Q6279
Fairer US politics desk compare	Each ID + category=Politics + sourceCountry=us
Debate-week slice	Each ID + q=debate + same from/to
Shared narrative heat	Stories + personWikidataId (one ID per poll)
Cut opinion roundups	excludeLabel Opinion or Non-news on either feed

Coverage shape (historical overviews - domains only): news.yahoo.com-style politics commentary linked to Trump; nwaonline.com-style White House visit coverage linked to Biden. Treat as pattern checks. A recent Stories shape for Q22686 can look like a multi-outlet foreign-policy or defense cluster that also mentions Trump - useful when the rivalry is a shared narrative, not a single URL.

For continuous politics product briefings, use Monitor US Politics News. For who wrote the coverage, use election journalist guides.

How to compare coverage across competitors

Whether rivals are companies or people, the rule is the same: one query per rival, identical window. Do not OR five tickers or two surnames into one bag if you need share-of-voice numbers.

Company Articles volume (same 30 days)

Rival symbol	About how many articles
LMT	~19,000
NOC	~9,200
RTX	~5,400

Lockheed-linked coverage outpaced Northrop and RTX - triage, not proof of wins.

Company Stories compression (same window)

Rival	Stories clusters (~)
LMT	61
NOC	26
RTX	19

Tens of thousands of articles become tens of narratives. Use Articles for volume; use Stories when an earnings print or award reprints (RTX outlook raise; Northrop Hawkeye award). Adjacent science clusters can appear on a prime symbol - tighten with q. Full move-detection sits in the competitor moves / Stories guide.

Side-by-side: company vs political competitors

	Defense primes	Trump vs Biden
Entity	companySymbol / companyId	personWikidataId
Typical 30-day scale	Thousands–tens of thousands of articles	Tens of thousands–hundreds of thousands
Stories role	Earnings / contract moves	Shared policy or campaign narratives
Common noise	Namesake firms, subsidiaries	Family members, entertainment Joes
Desk fence	Optional sourceGroup / q	Politics + US sourceCountry

What company coverage often looks like

Entity filters typically return contract and program wires. Historical pattern checks (domains only): marketwatch.com / theatlasnews.co style F-35 award framing for Lockheed; militaryleak.com style F135 engine funding for RTX.

For themes, skim titles per rival feed - or pass each set into Search Summarizer. Summarizer theory stays on that guide.

How to keep earned coverage vs press-release noise

Rival IR and campaign communications publish releases that index like news. For third-party coverage, add excludeLabel (Press Release, Paid Content, or Non-news) on the same entity query. Keep a second feed for official releases if you still need them.

Goal	Mechanism
Company allowlist	companySymbol or companyId
Person allowlist	personWikidataId
Event language	Optional q
Earned-only	excludeLabel
Publisher fence	Optional sourceGroup
Incremental poll	from / to or addDateFrom

Mixed stack example:

companySymbol=LMT + q=contract + excludeLabel Press Release - awards discussed by third parties, not only Lockheed’s wire.

Political stack example:

personWikidataId=Q22686 + category=Politics + sourceCountry=us + excludeLabel Non-news - US politics desk, less caption junk.

End-to-end CI playbooks

Playbook 1 - Five-prime defense morning brief

Resolve LMT, RTX, NOC, BA, GD (table above).

Poll Articles per symbol for the last 24 hours (addDateFrom or from/to).

Rank rivals by numResults; open the top two feeds.

For any spike, switch to Stories with that symbol and read articleCount.

Optional: Summarizer on the spike set for a six-bullet IR note.

Playbook 2 - Trump vs Biden weekly share-of-voice

Confirm Q22686 and Q6279.

Run both person filters for the last 7 days with Politics + US sources.

Record relative volume (do not treat as polls).

Diff top topics or skim titles for theme gaps.

If one shared narrative dominates, follow it on Stories with one ID at a time.

Playbook 3 - Award week for two primes

Parallel: companySymbol=LMT and companySymbol=NOC.

Add q=award OR contract OR Navy on both.

Compare counts; open Stories on the louder symbol.

excludeLabel Press Release if you want earned desks only.

When this workflow vs other Perigon surfaces

Situation	Prefer
Rival-company and rival-person API compares	This page
Deep person-only methodology	Political rival mentions guide
Earnings / contract as one narrative	Competitor moves / Stories guide
Full company / ticker / executive params	Company News guide + Entities docs
Defense or US politics product UI	Monitor Defense / Monitor US Politics
Who wrote the politics coverage	Election journalists guides
Editorial calendar gaps	Content strategy news API guide
News API vendor prices	Pricing comparison (separate SERP)

Beat scale at a glance

Company rivals and political rivals both need entity IDs - keywords fail differently (namesakes vs family).

In 2026-06-23–2026-07-23, LMT / NOC / RTX article volumes differed by multiples; Stories stayed in the tens of clusters.

In the same window, Trump vs Biden person volume differed by roughly an order of magnitude; Politics + US sources cut both feeds while preserving the gap.

Contract wires and candidate mention firehoses are evergreen shapes; re-run stats when you ship.

Key takeaways

Competitor news monitoring = resolve rivals + parallel Articles filters - companies or people.

Defense example: LMT, RTX, NOC, BA, GD - skip namesakes and Danish RTX A/S.

Political example: Trump Q22686 vs Biden Q6279 - skip Jr., Hunter, and other near matches.

Compare with one query per rival; use Stories when reprints are the problem.

Stack excludeLabel for earned media; use Signals Monitor pages for product briefings.

Get started: Articles sandbox · Entities · API reference · API pricing

News Sentiment API: Filter Positive, Negative, and Neutral Coverage

Oleksyj Mokrousov — Fri, 21 Aug 2026 10:09:42 +0000

Why keyword search alone cannot measure tone

A news search API that only matches words tells you what was covered. It does not tell you how the coverage reads. The same company, ticker, or topic can produce a product-launch celebration, a calm earnings wire, and a crisis investigation in the same week.

Keyword q, topics, and taxonomy keep the feed on-subject - they do not separate praise from criticism.

Teams building media intelligence, brand monitoring, or risk dashboards usually ask:

What is a news sentiment API on Perigon?

How do positive, negative, and neutral score ranges work?

How do you filter Articles and Stories by sentiment?

When should you use article filters vs average sentiment stats?

How do you compose sentiment with companies, sources, and dates?

The sections below answer each in order.

Try it live: Articles sandbox · Read the docs: Sentiment · Compare plans: API pricing

What is a news sentiment API?

A news sentiment API is not a separate product SKU. It is news data enrichment plus filters on the same search surfaces you already use. On Perigon, every indexed article can carry a sentiment object with three floats - positive, negative, and neutral - each on a 0 to 1 scale. Higher values mean a stronger signal for that tone.

You filter with the same Articles endpoint (/v1/all) you use for keywords, sources, and entities. Stories (/v1/stories/all) accept the same style of range filters on the aggregate tone of the cluster. For time-series dashboards, GET /v1/stats/avgSentiment returns average positive, negative, and neutral scores across a filtered set, optionally split by hour, day, week, or month.

That is the difference between reading every headline and asking the API for negative coverage, positive coverage, or a neutral wire-style slice of the same beat.

How positive, negative, and neutral scores work

Perigon does not collapse tone into a single label. Each article (and story aggregate) exposes three independent ranks:

Score field	Meaning	Filter params
positive	Strength of positive tone (0–1)	positiveSentimentFrom, positiveSentimentTo
negative	Strength of negative tone (0–1)	negativeSentimentFrom, negativeSentimentTo
neutral	Strength of neutral tone (0–1)	neutralSentimentFrom, neutralSentimentTo

From is inclusive minimum; To is inclusive maximum. You can set one bound or both. Because the three scores coexist, a practical pattern is to raise the tone you care about - for example a high negativeSentimentFrom for crisis monitoring - rather than treating sentiment as a single mutually exclusive enum.

Use ranges when you need a threshold (“show me clearly negative pieces”), not when you only need the raw scores on each hit. Unfiltered search already returns sentiment on matching articles so you can chart or sort in your own app.

How to filter Articles and Stories by sentiment

Articles API (/v1/all)

Pass any combination of the six range params. Common patterns:

Goal	Typical filters
Strongly negative coverage	Raise negativeSentimentFrom (e.g. toward the high end of 0–1)
Strongly positive coverage	Raise positiveSentimentFrom
Mostly neutral / wire tone	Raise neutralSentimentFrom
Cap a tone	Use the matching …SentimentTo upper bound

Includes work like other numeric filters: set the bounds that describe the slice you want, then layer topic, company, or source filters so sentiment is measured inside a known beat.

Headlines (/v1/headlines) accept the same sentiment range params when you need a headline-oriented surface.

Stories API (/v1/stories/all)

Story filters use the same param names against the cluster-level aggregate sentiment. Prefer Stories when you care about the tone of a narrative (one event, many reprints) rather than the tone of every individual article. Clustering mechanics stay in the News Stories API guide - here the only decision is article-level vs story-level tone.

Article filters vs average sentiment stats

Need	Use	What you get
A list of negative (or positive) articles	Articles with sentiment range filters	Hits plus per-article sentiment
Tone of a clustered narrative	Stories with sentiment range filters	Clusters with aggregate sentiment
How average tone moved over time	/v1/stats/avgSentiment	Average positive / negative / neutral, optionally split

/v1/stats/avgSentiment reuses the same Articles-style filter set (AllEndpointParams) so you can pin a company, source group, or date window, then set splitBy to HOUR, DAY, WEEK, MONTH, or NONE. That is the dashboard path: one filtered corpus, a time series of average tone - not a second search product.

Keep Search Summarizer for executive briefings of a filtered set. Sentiment filters and avgSentiment answer “what is the tone?”; summarization answers “what should we take from these articles?” Link the AI News Summaries guide when the deliverable is a briefing, not a score.

Compose sentiment with companies, sources, and dates

Sentiment is most useful as a second pass after you know who and where.

Brand or ticker reputation: pin companyDomain or companySymbol, then raise negativeSentimentFrom for risk alerts (entity params are covered in the Company News API guide).

Trusted publishers only: add source or sourceGroup so tone is measured on outlets you trust, not the entire open web.

Fresh windows: use from / to or addDateFrom so crisis monitors and reputation charts stay on the current incident, not years of archives.

Topic or taxonomy desks: keep the beat with topic, category, or taxonomy filters, then apply sentiment ranges so finance or health coverage can separate praise from criticism inside the same vertical.

A common media monitoring pattern is company (or topic) + trusted sourceGroup + addDateFrom + a negative sentiment floor for incremental pulls.

What results look like

Article hits include a sentiment object with positive, negative, and neutral floats. Your UI can show tone chips, sort by the dominant score, or feed scores into a chart without a second enrichment call.

Story results expose aggregate sentiment across the cluster - useful when one narrative reprints widely and you want the story’s overall lean, not thirty near-identical article scores.

avgSentiment returns timed buckets (when splitBy is not NONE) with average positive, negative, and neutral values for the filtered corpus - the input for reputation and crisis dashboards.

Use cases

Brand reputation and crisis alerts

Scope to the brand with company filters, raise negativeSentimentFrom, and poll with addDateFrom. Route matches to an on-call channel; use avgSentiment with splitBy=DAY for a simple tone trend beside the alert list.

Competitive coverage tone

OR rival companyDomain values, keep a shared sourceGroup, and compare either filtered negative/positive slices or parallel avgSentiment series per competitor.

Neutral wire feeds for research products

Raise neutralSentimentFrom when the product should prefer straight reporting over opinionated framing - then still allow users to open the full unfiltered set when they want every angle.

Narrative-level risk on Stories

During a fast-moving event, filter Stories with a negative floor so dashboards track hostile or alarming storylines, not every reprint’s micro-variation in score.

When to use which sentiment path

Job	Prefer
Inbox of negative (or positive) articles	Articles + range filters
Tone of one event across outlets	Stories + range filters
Reputation / crisis chart over time	/v1/stats/avgSentiment + splitBy
Leadership-ready prose digest	Search Summarizer on an already filtered set

Key takeaways

A news sentiment API on Perigon is score enrichment plus filters on Articles, Stories, and /v1/stats/avgSentiment - not a separate SKU.

Each piece carries positive, negative, and neutral scores from 0 to 1; filter with …SentimentFrom / …SentimentTo ranges.

Use Articles for per-article tone slices, Stories for cluster aggregates, and avgSentiment for time-series averages.

Compose sentiment after company, source, topic, and date filters so tone is measured inside a known beat.

Keep summarization for briefings; keep sentiment for thresholds and charts.

Get started: Sentiment · API reference · Articles sandbox · API pricing

Best News Sources: AI Top Lists vs Perigon's top100 Source Group

Oleksyj Mokrousov — Tue, 28 Jul 2026 10:07:02 +0000

Why “best news sources” lists disagree

Ask three assistants for the top news sources - with domains - and you get three confident shortlists that optimize for different jobs. One model ranks wire and reputation brands.

Another ranks monthly traffic. A third mixes both and folds in aggregators. That is useful brainstorming. It is a weak foundation for a production news source allowlist, where the publisher set must stay stable across Articles and Stories jobs.

We compared ChatGPT, Claude, and Gemini top-8 answers, then lined them up against Perigon’s public top100 source group (ID 15, display name Most popular - about 94 domains). Across the three AI lists, only three publishers appear on every roster: BBC, The New York Times, and CNN. Everything else is a bias toward wires, portals, or partisan traffic leaders.

This article covers:

Why AI-generated best news sources lists disagree

What top100 covers that short lists drop

How to monitor general news with that source group

How to filter news by source, topic, company, and date inside the pack

Try it live: Sources sandbox · Docs: Sources and source groups · Plans: API pricing

Vertical packs (different SERPs): top25finance · healthcare trade pubs. This page owns the general most popular pack only.

Why AI top-8 news lists are not a production allowlist

The disagreement is not noise - each model answers a different reading of “top”:

ChatGPT leans influence and international desks: Reuters, Associated Press, BBC, NYT, Washington Post, WSJ, Bloomberg, CNN. Strong for wires and prestige brands; light on pure traffic portals.

Claude leans Similarweb-style traffic: Yahoo (including Japan), BBC, NYT, CNN, Fox News, USA Today, Daily Mail. Strong for visit volume; includes aggregator/portal surfaces that are not traditional newsrooms.

Gemini mixes both and adds The Guardian, Reuters, Yahoo, and MSN - calling out that portals often rank high because they are homepages, while original reporting still comes from wires and newspapers.

What AI does	What breaks in production
Returns a neat “top 8”	Misses local metros, lifestyle desks, and half the opinion spectrum your product may need
Sounds authoritative	Different model → different publishers → different alert quality
Optimizes for one ranking lens	Traffic ≠ reputation ≠ “trusted” - and none of those lenses equals a maintained group name

Treat LLM shortlists as research signals. Do not paste them into source= forever and call the feed done.

The fuller picture: top100 (most popular)

Field	Value
Name	top100
Display name	Most popular
Source group ID	15
Size	~94 domains
Scope	Top most popular sources globally

Pass sourceGroup=top100 on Articles (/v1/all), Headlines, or Stories. Inspect members via the Sources API with the same group name - without dumping every domain into this article twice.

Rather than stopping at eight household names, the group spans the lanes that show up when teams actually ship a popular news feed:

1) Wires and global brands - Reuters, AP, BBC, NYT, Washington Post, WSJ, Bloomberg, CNN, and peers the reputation-style lists already name.

2) High-traffic digital and cable - Fox News, USA Today, Daily Mail, HuffPost, NBC, CBS, ABC, and similar mass-reach desks.

3) U.S. metro and regional papers - Los Angeles Times, Boston Globe, Chicago Tribune, Seattle Times, Miami Herald, and other city desks short “global top 8” lists almost never assemble.

4) Business and markets adjacent - CNBC, Forbes, Yahoo Finance, Quartz - without requiring the finance-only top25finance pack.

5) Opinion and partisan digital - outlets across the spectrum (from Breitbart and Daily Wire to Daily Kos and Raw Story) so a “popular” feed is not accidentally center-only.

6) Lifestyle and culture - People, BuzzFeed, Cosmopolitan, Variety, Vanity Fair - the consumer layer pure politics lists drop.

7) International English desks - Al Jazeera, South China Morning Post, The Guardian, Telegraph, and others beyond a U.S.-cable shortlist.

How the group compares with the AI picks

Almost every domain the three models named is already inside top100. The practical gaps run the other way: short lists never assemble metro papers, lifestyle titles, or the broader opinion set that a “most popular globally” pack includes.

Honest misses relative to the AI traffic answers:

yahoo.co.jp (Claude’s global traffic leader) is not in this snapshot - the pack includes yahoo.com / finance.yahoo.com instead.

msn.com (Gemini) is not listed as such; the group includes Microsoft’s ms.now surface. If you need a specific portal hostname, add it with source= or a private group.

That is the point of a curated sourceGroup: one reusable name for the popular-publisher fence, not a chat paste that changes when you switch models.

How to monitor news with top100

Scope popular publishers first, then keywords or entities. Without a publisher gate, open-web search for politics, markets, or breaking topics pulls blogs, SEO farms, and press-release mills alongside serious desks. Lock the outer fence with sourceGroup=top100, then narrow.

Pattern on Articles: pass sourceGroup set to top100, add q for the beat you care about, and poll with from / to or addDateFrom for digests. For a company or person watch inside popular outlets, stack companySymbol / companyId or personWikidataId the same way - the Company and People guides own the full entity cookbook; here the group is the allowlist.

Use the same sourceGroup on the Stories API when one event reprints across many major outlets - you track the narrative cluster once instead of every mirror URL. For a short briefing of that filtered set, pass results into Search Summarizer. Vertical desks that need trade pubs only should use the industry packs (finance, healthcare, automotive, industrial) rather than stretching top100 into a niche B2B feed.

Filter popular news by source, topic, company, and date

Goal	Mechanism	Notes for general feeds
Popular-publisher allowlist	sourceGroup=top100	Most-popular global pack (15)
One-off domain	source / excludeSource	Portals or titles missing from the snapshot
Who is mentioned	companyId / companySymbol / people filters	Inside the group
What it is about	topic, category, taxonomy	e.g. Politics slice inside top100
When	from / to / addDateFrom	Digests and incremental monitors

Creating private forks of the pack (your own curated list on top of or instead of top100) lives in the Source Groups guide - this page only applies the public name.

When an AI list is a brainstorm vs when you need top100

Situation	Prefer
Ideation slide (“brands we recognize”)	AI shortlist - then verify
Production best news sources feeds and alerts	top100 (15)
Finance-only or healthcare-only desk	Vertical pack (top25finance, healthcare trade pubs, …)
Must-have portal hostname absent from the ~94	Private group or source=
Publisher metadata (geography, paywall, traffic)	Sources API + group name

Scale inside the pack (last 30 days)

Live Articles counts for 2026-06-19 through 2026-07-19 (pubDate window):

About 604,000 articles matched sourceGroup=top100.

About 28 million articles matched an open q=* baseline in the same window - so the popular pack is a small, high-signal slice of total index volume (on the order of 2%).

About 110,000 of the top100 hits also carried category Politics.

About 38,500 Stories clusters matched sourceGroup=top100 in the same window - useful when you care about narrative heat, not every URL.

Round large numResults in product copy; very large baselines can sit near plan or index caps, so prefer the relative comparison (popular pack vs open web) over treating any single integer as exact forever.

Key takeaways

AI best news sources top-8 lists disagree because they optimize for reputation, traffic, or a mix - only BBC, NYT, and CNN were unanimous across the three we compared.

top100 (15) is the maintained most popular allowlist (~94 domains): wires, national desks, metros, opinion, lifestyle, and international English - not eight chat suggestions.

Filter news by source with sourceGroup=top100, then stack q, entities, category, and dates for desk-specific feeds.

Use LLM lists to brainstorm; use the curated group for production. For industry-only SERPs, switch to the matching vertical pack instead of overloading top100.

Get started: Sources sandbox · Sources and source groups · API reference · API pricing

Left vs Right Political Journalists Compared

Oleksyj Mokrousov — Tue, 28 Jul 2026 10:05:39 +0000

Building political media monitoring without ideology fields

Teams searching for left vs right political journalists usually need a political monitoring system: two reusable byline datasets, transparent rules, and stable IDs they can apply on article search. They do not need an editorial ranking of reporters.

Perigon does not assign left/right ideology to journalists. There is no journalist-level lean parameter. Any “left vs right” framing in your product comes from publisher clusters you define, then from journalists whose profiles match those publishers. This guide teaches that reproducible methodology - data quality, verification, and journalist identity resolution - so the dataset stays accurate when people change employers.

Why are keyword searches unreliable for partisan media reporters?

How do customer-defined publisher clusters create comparable datasets?

What is the end-to-end workflow from cluster → resolved IDs → Articles?

How do you keep datasets trustworthy as affiliations change?

When should you use Journalists vs Sources vs People?

The sections below answer each in order. Full Journalists parameter reference lives in the Journalists API guide and the Entities docs linked above; this page owns the monitoring methodology.

Try it: Journalists sandbox · Docs: Entities · Pricing: API pricing

Why keyword ideology search fails

Searching q for “liberal,” “conservative,” “left,” or “right” does not produce a defensible partisan journalist list. Those tokens appear in quotes, horse-race copy, sports “left tackle,” and photo captions. Different people share the same byline string. Keyword hits are not reproducible ideology membership.

Publisher clustering outperforms keyword-based ideology search because membership is explicit: you decide which domains belong in Pack A and Pack B, document that choice, and resolve journalists against source (optionally with category=Politics, country=us, or label = Opinion). Two engineers re-running the same pack definitions get the same discovery inputs. That is the foundation of media lean journalist discovery as engineering practice - not as a claim about individuals’ beliefs.

Publisher clusters are defined by the customer

In this workflow, “left” and “right” are labels on your publisher packs, not attributes returned by the Journalists API.

Concept	Owner
Which domains sit in Pack A / Pack B	Your product, research, or compliance rules
Whether Opinion-heavy sites belong in a pack	Your product
Journalist profile fields (title, topSources, id)	Perigon index
Ideology of a person	Not provided by the API

Different organizations choose different outlet lists for good reasons: brand risk, geographic focus, inclusion of opinion vs newsroom domains, licensed publishers, or internal media-bias taxonomies. Two customers can both build left vs right journalists monitors and disagree on whether a given domain belongs in a pack. That disagreement is expected. Document the pack version (domains + date + rationale) next to any saved ID list so audits can reproduce results.

Example pack shapes (illustrative only - replace with your approved domains):

Your label	Role in the system	Example domain pattern
Pack R	Customer-defined “right” publisher set	Domains your policy treats as that cluster
Pack L	Customer-defined “left” publisher set	Domains your policy treats as that cluster

Do not treat any sample domain list in a blog post as Perigon’s official ideology map. The API only answers: which journalists are associated with the publishers you queried.

Reproducible workflow: cluster → resolve → verify → save → apply

Use the same pipeline for both packs. Keep pack membership metadata on every saved row.

Define publisher clusters
Store Pack L and Pack R as versioned domain lists (and optional rules such as “Opinion allowed”).

Resolve journalists
On /v1/journalists/all, query with source set to the pack’s domains. Narrow with category, country, label, or minMonthlyPosts as your quality bar requires. For known bylines, use name / twitter and then verify.

Verify before save
For each candidate, confirm title and topSources still match the pack you intend. Reject near-matches, empty activity, or profiles whose top publishers fall outside the pack.

Save reusable journalist IDs
Persist journalistId, pack label, pack version, verification timestamp, and optionally the topSources snapshot you accepted.

Use journalistId on Articles
On /v1/all, pass journalistId (OR) or excludeJournalistId (AND) to build feeds. The ID identifies the byline match - it does not encode ideology. Ideology, if any, remains the pack label you attached in step 4.

That pipeline is the primary topic of this page: building publisher-based journalist datasets for political media intelligence, while still matching search intent around left vs right political journalists.

Journalist identity resolution and byline disambiguation

Journalist identity resolution means mapping a human byline to a single stable id in the journalist index. Common failure modes:

Failure	Mitigation
Shared or similar names	Compare title, Twitter handle, and topSources; do not pick the first row
Syndication noise	High post volume across many domains can pull in off-pack publishers - require pack overlap in topSources
Empty or stale profiles	Prefer profiles with recent updatedAt / non-zero avgMonthlyPosts when activity matters
Domain filter returns zero	Some brands publish under alternate hosts; fall back to name resolve, then verify sources

Byline disambiguation is a data-quality gate, not a political judgment. If title and topSources do not support membership in the customer pack, do not save the ID into that pack’s dataset.

Data quality: verify title and topSources every time

Before a profile enters production:

1) Read title - does the role match the desk you monitor (politics, opinion, correspondence), or is it sports/lifestyle collision?

2) Read topSources - do the leading domains intersect your pack version?

3) Optionally check topLabels / topTopics as secondary signals, not as ideology classifiers.

4) Record who verified the row and when.

Skipping verification is how partisan media reporters datasets silently fill with wrong people. Reproducibility requires the verification step to be part of the written method, not an optional polish.

Affiliations change: refresh saved journalist IDs

Journalists change employers, shows, and syndication patterns. A journalistId remains a useful primary key, but pack membership is time-bound:

Schedule a periodic refresh (for example monthly or each pack-version bump).

Re-fetch /v1/journalists/{id} or re-run name resolve.

Re-check title and topSources against the current pack.

Move IDs between Pack L and Pack R only when your policy says the publisher footprint changed - and log the change.

Retire IDs that no longer meet the quality bar.

Evergreen monitors depend on this maintenance loop. Static “lists of left vs right journalists” scraped once will drift.

Integrate Journalists API results with the Articles API

After IDs are verified and labeled with a pack version:

Articles parameter	Use in political monitoring
journalistId	Include bylines from one pack (or a union you explicitly label)
excludeJournalistId	Drop bylines that flood or fail QA
author / excludeAuthor	Name-only fallback when an ID is not yet resolved - weaker than IDs

Combine with your usual article filters (q, dates, category) for event language. Keep pack ideology metadata in your datastore; do not expect Articles responses to return left/right on the journalist object.

When to use Journalists vs Sources vs People

Monitoring question	API family
Which writers match our publisher packs?	Journalists → save journalistId
Which publishers define the packs / outlet skew?	Sources / source groups
Which people are mentioned as subjects (candidates, officials)?	People (personName, personWikidataId)

Mixing these layers is a common design bug: treating a mentioned politician as a byline, or treating a source-group lean pack as a journalist ideology field. Keep writer, publisher, and subject as separate allowlists.

Resolve smoke tests (not rankings)

The following IDs are resolution examples from live lookups - used to illustrate verification, not to rank or endorse anyone. Each row is “this profile resolved; confirm topSources against your pack before production use.” Ideology is only whatever pack label you attach after verification.

After querying a customer Pack R (illustrative domains such as foxnews.com / nationalreview.com / thefederalist.com / washingtonexaminer.com):

Name	Resolved id	Verification cue
Bret Baier	377c544662ed4358921cba67a336ef4f	Title + foxnews.com in topSources
Byron York	677cd5fe712f44b680f7ec815edbd365	washingtonexaminer.com in topSources
Rich Lowry	67a37bc03b434bd0a481d52fdda47b56	nationalreview.com in topSources

After querying a customer Pack L (illustrative domains such as nytimes.com / washingtonpost.com / huffpost.com):

Name	Resolved id	Verification cue
Jamelle Bouie	891fe2e6b12a4518b61d045f4172fad5	Columnist title + nytimes.com in topSources
Jennifer Rubin	dff54a11b7954148b08a39e07403b035	Opinion-writer title; re-check live topSources before save
Rachel Maddow	e93c35d952cc4dd88d68c38b748f3ca4	Host title; confirm current topSources (domain filters for some TV brands can return empty - name resolve + verify)

If verification fails, do not keep the ID in that pack’s dataset. Replace with another resolved profile that passes your gates.

Key takeaways

Search intent for left vs right political journalists is best served by publisher-cluster datasets, not keyword ideology queries.

Perigon does not label journalists as left or right; pack definitions and ideology labels are yours.

Workflow: define clusters → resolve → verify title / topSources → save versioned IDs → apply journalistId on Articles.

Refresh saved IDs as affiliations and topSources change.

Use Journalists for writers, Sources for publishers, People for mentioned subjects.

Get started: Journalists sandbox · Entities · API pricing

Perigon SDK Overview: Official Client Libraries for the News API

Oleksyj Mokrousov — Tue, 28 Jul 2026 10:04:08 +0000

The real question is not “is there an SDK?”

Most teams already know Perigon publishes an official news SDK. The harder API onboarding question is whether your product should call the News API through that software development kit or through raw HTTP / REST forever.

This page is only a SDK vs HTTP / REST vs SDK decision guide. Exact packages, install steps, and typed-client ergonomics live on Perigon SDKs plus the sibling install and typed-client posts. Articles search design stays on the practical news API guide.

What problem does a Perigon SDK actually solve on the API integration path?

When does a multi-language SDK change the build-vs-buy transport decision?

When should you choose news SDK clients instead of raw REST?

Which architecture tradeoffs still favor owning HTTP yourself?

The sections below answer each in order.

Read the docs: Perigon SDKs · Developer home: Getting started · Compare plans: API pricing

What is the Perigon SDK for, architecturally?

The Perigon SDK is Perigon's official news SDK: maintained news API client libraries that sit between your application and the REST News API. From an architecture view, the SDK is a transport abstraction - your code talks to a client object; the client owns serialization, auth attachment, and response decoding.

That matters for developer productivity and long-term maintenance more than for “having a package.” Without an official client, every service invents its own thin wrapper. Six months later you have three incompatible helpers, none of which track docs changes. With the SDK, onboarding a new engineer means “use the supported client,” not “copy the curl from Slack.”

The SDK is not a different API and not a substitute for learning which filters to pass. It changes who maintains the HTTP edge - Perigon’s official client libraries versus your team.

Multi-language SDK coverage as a staffing decision

A multi-language SDK is less about collecting languages and more about matching the runtimes you already staff. If your backend is already standardized on a supported stack, picking the news API SDK for that stack is usually the default API integration path. If your edge workers, ETL jobs, and mobile backends each speak a different language - and only one of them has an official client - you need an explicit policy: SDK where supported, thin REST where not, rather than forcing one language’s package into every process.

Unsupported runtimes are not a failure of the SDK; they are a signal to stay on HTTP (or request another binding via the SDKs docs) instead of pretending a missing client exists.

REST vs SDK: decision scenarios

Situation	Prefer	Why
Spike in Postman / curl to learn filters	Raw HTTP	Fastest feedback loop; no package lifecycle
Production service on a supported runtime	Perigon SDK	Lower maintenance; shared patterns across teams
Many services, one platform team	SDK (client library vs REST)	One supported onboarding path
Exotic runtime or strict “no third-party clients” policy	HTTP you own	You accept wrapper maintenance
Query design still fluid	Learn filters first, then lock transport	Do not block product learning on packaging

SDK vs raw REST is rarely about feature parity - both hit the same endpoints. The tradeoff is maintenance, onboarding, and long-term support: who upgrades when parameters or models change, and how many home-grown clients you are willing to babysit.

Prefer the SDK when transport should be boring and identical across services. Prefer HTTP when you need maximum control, minimal dependencies, or a runtime outside the official set.

Architecture tradeoffs that still favor owning HTTP

Some teams should keep raw REST even when an SDK exists:

1) Compliance / supply-chain rules that freeze third-party client libraries

2) Ultra-thin edge workers where every dependency byte is budgeted

3) Polyglot glue that already centralizes HTTP in an internal gateway - the gateway speaks REST; apps never see Perigon directly

4) Experimental research notebooks that change weekly and should not pin SDK majors

Those are conscious HTTP client vs SDK choices. If none of them apply, choosing the official client libraries is usually the lower-risk default.

How to sequence the decision (without installing anything here)

Decision	Where to go next
SDK vs HTTP for this service	This overview
How to install and authenticate safely	SDK install best-practices guide
Why typed clients help large codebases	Typed SDK clients / DX guide
Which filters and feeds to build	Practical news API guide

Key takeaways

Treat the Perigon SDK as transport ownership and developer productivity, not as a second News API.

Multi-language SDK coverage answers “can my staffed runtime use an official client?” - not “which command do I run?”

Prefer the SDK for production on supported stacks; prefer raw REST for spikes, exotic runtimes, or deliberate HTTP ownership.

This page only answers when to use SDK vs HTTP; packages, keys, and typed DX live elsewhere.

Get started: Perigon SDKs · API pricing

Monitor Middle East Conflict News

Oleksyj Mokrousov — Tue, 28 Jul 2026 10:02:34 +0000

Why teams monitor Middle East conflict news

The Middle East is rarely a single story. On any given week, coverage spans Israel-Gaza, Iran and its nuclear file, Lebanon and Hezbollah, Red Sea shipping attacks, and the diplomacy around all of them - each moving at a different speed. Analysts, risk teams, and newsrooms that watch the region need to catch escalations early without drowning in duplicate wire copy, and they need to tell a genuine turning point apart from routine daily volume.

Keyword alerts alone break down here. A single broad term returns hundreds of thousands of articles a month, most of them reprints of the same handful of developments. The job is to watch several theaters in parallel, get told when something changes, and keep a running narrative for each front.

What makes Middle East conflict news hard to monitor?

How do you set up a Signal to watch the region on perigon.io/home?

Which Articles and Stories filters scope a multi-theater beat?

When should you rely on Signals vs Articles vs Stories?

The sections below answer each in order.

Set up a Signal: perigon.io/home · Try the API: Articles sandbox · Compare plans: Signals pricing

What monitoring the region means in practice

There are two distinct jobs, and they map to two different tools.

A Signal is a continuous watch. You describe the region and the kinds of developments you care about in plain English, and it keeps working in the background - delivering Middle East war alerts in real time or as a scheduled briefing. That is the difference from a one-off search: you set intent once, and coverage comes to you.

Stories are the momentum layer. Perigon clusters related articles into a single evolving narrative, so an escalation that generates thousands of articles shows up as one trackable cluster you can follow over time. That is what makes regional conflict monitoring manageable across five theaters at once.

Use Signals for the live watch, Articles for precise historical queries, and Stories to see which fronts are actually accelerating.

Set up a Signal

Go to perigon.io/home and describe the beat in plain language - the assistant helps you refine scope, conditions, and how results are delivered (email, webhook, or a connector such as Slack). For a multi-theater region, name the fronts explicitly so nothing is dropped.

Copy-paste starting points:

Real-time escalation alert

Alert me to major escalations in the Middle East - airstrikes, ceasefire announcements, and cross-border attacks involving Israel, Gaza, Lebanon, Iran, or Red Sea shipping. Send each as it happens to my Slack channel.

Morning regional briefing

Every morning, summarize overnight developments across Israel-Gaza, Iran, Lebanon and Hezbollah, and Red Sea shipping. Group the summary by theater and include source links.

Diplomacy and de-escalation watch

Track statements, resolutions, and inspections from the UN Security Council and the IAEA related to the Middle East, and flag any ceasefire talks or nuclear-inspection developments.

Because escalations are event-like, Perigon delivers them in real time; a "summarize every morning" prompt is treated as a scheduled digest instead. You can run more than one Signal - a fast alert plus a calmer daily briefing is a common pairing.

Theaters and institutions to scope

A durable regional watch is organized by theater and by the institutions that shape de-escalation, not by whichever name is in today's headline. Evergreen fronts worth naming in a Signal or query:

Israel-Gaza - the highest-volume front, covering military operations, humanitarian access, and ceasefire cycles.

Iran - the nuclear file, proxy networks, and sanctions-linked tensions.

Lebanon and Hezbollah - cross-border exchanges and their spillover risk.

Red Sea shipping - attacks on vessels near one of the world's busiest maritime corridors (a security and freight-disruption angle - for crude-price and energy-market coverage, use a dedicated oil/energy watch instead).

Diplomacy - the UN Security Council and IAEA as standing institutions whose statements and resolutions often mark turning points.

Keeping these as roles and geographies - rather than one-off personalities - is what makes the Signal and the queries below reusable month after month.

Articles API recipes for the region

On the Articles API (/v1/all), build one query per theater and keep them narrow with Boolean q. Pair Israel, Gaza, or Hamas with escalation terms like strike, ceasefire, or offensive; pair Iran with nuclear, sanctions, or proxy; pair Red Sea or Houthi with vessel, shipping, or attack. Add category set to Politics to bias toward hard-news coverage, and sortBy set to date for the newest first.

To weight regional reporting, use sourceCountry for publisher geography or country for the story's associated country, and reach for language when you need Arabic-language or English-only slices. Stack from and to for a fixed window, or sortBy set to date with a rolling window for a live feed. Keep each theater as its own query so a spike in one front does not bury the others.

Stories API recipes for tracking momentum

The Stories API (/v1/stories/all) is where a multi-theater beat becomes readable. The same theater q you used on Articles returns clusters instead of individual articles, so you follow a development as one narrative rather than re-reading a hundred reprints. Sort by article count or recency to surface the fastest-moving fronts, and use an updatedFrom window to see which clusters are still active rather than cooling off.

The payoff is scale compression: broad theater keywords that return six-figure article counts collapse into a few hundred Stories clusters (see the numbers below). For how clustering groups related coverage into trackable narratives, see the news clustering guide; this page keeps the focus on applying it to the region.

When to use Signals vs Articles vs Stories

Goal	Use	Why
Be told the moment a front escalates	Signal (real-time)	Continuous watch, delivered to inbox, Slack, or webhook
A grouped daily read across theaters	Signal (scheduled)	One briefing, organized by front
Precise historical or filtered query	Articles API	Full Boolean, category, geography, and date control
Follow one development over time	Stories API	Clustered narrative and momentum, not raw article volume
See which theater is accelerating	Stories API	Compare cluster counts and recency across fronts

Beat scale at a glance

A few evergreen facts anchor why this beat needs structure: the region runs multiple simultaneous theaters, the UN Security Council carries standing authority over conflict resolution, the IAEA monitors nuclear activity, and the Red Sea remains one of the world's busiest shipping corridors - so a single week routinely produces parallel, fast-moving stories.

The live index shows the volume problem directly. Over the 30 days ending July 17, 2026, broad theater keywords returned very large article counts - roughly 345,000 for Iran-tensions terms, about 222,000 for broad Middle East conflict terms, and around 215,000 for Israel-Gaza terms - with Lebanon and Hezbollah near 88,000, Middle East coverage inside the Politics category about 77,000, regional institutions near 59,000, and Red Sea shipping around 13,000. (These are wide keyword slices, so treat them as relative signal, not precise tallies.)

The Stories layer is what makes that tractable. Across the same window, those slices collapsed into a few hundred narrative clusters each - on the order of 800 for Iran, 600 for Israel-Gaza, 570 for broad Middle East conflict, 250 for Middle East politics, 230 for Lebanon, 140 for regional institutions, and about 65 for Red Sea shipping. In other words, hundreds of thousands of articles became a few hundred stories to actually read.

Key takeaways

Middle East conflict news is a multi-theater beat - scope Israel-Gaza, Iran, Lebanon, and Red Sea shipping as separate fronts, not one keyword.

Set an AI Signal on perigon.io/home for real-time Middle East war alerts or a theater-grouped morning briefing.

Use the Articles API for precise Boolean, category, geography, and date queries per front.

Use the Stories API to turn six-figure article volume into a few hundred trackable clusters and see which theater is accelerating.

Organize the watch around evergreen theaters and institutions (UN, IAEA) so your Signals and queries stay reusable.

Get started: perigon.io/home · Signals pricing

Request News Api to index Publisher

Oleksyj Mokrousov — Mon, 27 Jul 2026 14:08:29 +0000

What to do when a publisher is missing from the news API

Perigon indexes hundreds of thousands of publishers, but sometimes the one outlet your product depends on - a niche trade site, a regional paper, or your own brand site - is not in the results yet. The fastest fix is usually to ask Perigon to add it, then confirm whether that is a support request or a plan upgrade.

This is a support and licensing guide, not an endpoint tutorial. It answers four questions:

Why is the publisher I need missing from the news API?

How do I ask Perigon to cover it - or add my own site?

How do live chat and email support work?

Which plans unlock request to index sources, an SLA, and a shared Slack channel?

Check what's indexed: Source Explorer · Ask for coverage or a demo: API pricing · Source docs: Sources and source groups

Why a publisher may be missing from the news API

Before you file a request, confirm the outlet is genuinely absent rather than filtered out. A source can be:

1) Indexed under a different domain or subdomain than the one you searched.

2) Excluded by your current query filters.

3) Present but low-volume, so it rarely surfaces.

Search the domain in Source Explorer or the Sources API first. If it truly is not there, you are looking at one of two different needs - and they route differently.

You want	This is	How to get it
Bundle domains that already exist into a reusable, named filter	Custom Source Groups (self-serve)	Source Groups API guide
Perigon to ingest a publisher that is not in the index yet	Request index for Sources (Commercial)	Request via support or sales

Put simply: Custom Source Groups organize sources Perigon already has, while Index request ask Perigon to add one it does not. This guide covers the second path. If the outlet is already indexed, skip the request and group it yourself.

How to request a publisher or add your own site

Adding a publisher is a human review step, not a self-serve API call, so the request goes through Perigon's support channels. Contact support, describe the outlet, and explain why your feed needs it. Perigon then evaluates the source for ingestion. First-party requests - adding your own news site or brand blog - follow the same process as third-party outlets.

Perigon can consider a range of publisher types, including:

1) Mainstream and wire outlets

2) Regional and local newspapers

3) Niche and trade publications

4) First-party sites you own and publish

Eligibility for new sources depends on your plan (see below). If you are on a lower tier and need custom ingestion, the request naturally becomes a sales conversation about moving to Commercial.

What to include in your request

A complete request is triaged faster. Include:

Domain - the exact publisher domain (for example example-tradedesk.com), plus any subdomains that carry articles.

Publication name - the readable outlet name so it can be matched or created.

Reason - the beat or use case, which helps prioritize the source.

Sample article URLs - two or three live links that show the crawl target and article structure.

Ownership - for your own site, confirm you own the domain and can grant publishing access.

How live chat and email support work

Perigon offers two ways to reach a human, and both work for a coverage request.

Live chat opens from the contact widget on every page and routes by intent:

Coverage requests - a missing publisher - go to support, where sources are evaluated.

Plan-upgrade questions, such as unlocking New Sources on Commercial, go to sales.

You can contact sales:

Or book a demo:

Email support is available on every plan for account and product questions, including coverage requests you would rather send as a written thread with your domain list attached.

Use live chat for quick questions ("Can you cover this outlet?", "Which plan do I need?") and email when you want a documented request. Either way, state clearly that you are asking to add a source so it is triaged correctly. Contact and demo booking also live on the pricing page.

Which plans unlock indexing of new sources that api do not have, SLA, and shared Slack

Email support is included on every plan, so account and product questions are never gated behind an upgrade. The heavier enterprise support and data features are Commercial-only:

New Sources indexing - Perigon adding publishers you request, including first-party sites.

Upgraded Support - a higher support tier beyond standard email.

SLA - a formal service-level agreement.

Shared Slack Channel - a direct support line between your team and Perigon.

Do not assume these ship on Free, Basic, or Plus. If your build needs custom ingestion, a guaranteed SLA, or a shared Slack line, that is the signal to talk to sales.

Plan and license matrix

This table is scoped to the support and licensing question this article answers, not the full usage matrix. Limits and pricing change, so treat the pricing page as the source of truth.

Feature	Free	Basic	Plus	Commercial
Data License / Who Qualifies	Anyone	Eligible Startups	Eligible Startups	All Businesses
License	Personal	Limited (Startup)	Limited (Startup)	Full Commercial
Email Support	Yes	Yes	Yes	Yes
New Sources Indexing	—	—	—	✓
Upgraded Support	—	—	—	✓
SLA	—	—	—	✓
Shared Slack Channel	—	—	—	✓

Commercial pricing is custom; contact sales rather than expecting a fixed number on the page.

FAQ

How long does it take to add a publisher? Perigon reviews each source case by case. In general it takes few days - from 12h to 48h.

Can I request a mainstream or niche trade outlet? Yes, both. The format is the same: domain and sample URLs.

Can I add my own news site or brand blog? Yes. First-party domains are handled like any other request - just confirm you own the site and can grant publishing access.

Should I contact support or sales? Start with support for the coverage question. If unlocking custom sources means upgrading, live chat routes the upgrade to sales, or you can start from the contact options on the pricing page.

Key takeaways

Confirm the outlet is truly missing, not just filtered out, before you file a request.

Custom Source Groups organize existing sources; New Index for Sources ask Perigon to add new ones.

Request coverage through live chat or email support - email is available on every plan.

New Custom Sources, Upgraded Support, an SLA, and a Shared Slack Channel are Commercial-only.

Include the domain, publication name, reason, and sample URLs, and check the pricing page for current plans.

Get started: Source Explorer · Sources and source groups · API pricing

Top Election Journalists: Who Covers Campaigns and Ballots (and How to Find Them)

Oleksyj Mokrousov — Mon, 27 Jul 2026 14:06:16 +0000

Why teams need an election journalist list

Election journalists sit at the center of campaign coverage, ballot fights, polling explainers, and voting-rights reporting. Keyword alerts for “election” or a last name pull sports “races,” foreign contests, and every photo-caption byline collision - while the political reporters who actually own campaigns, polls, or election administration stay hard to inventory.

Teams building outreach lists, citation trackers, or campaign-news products usually ask:

What does “top election journalists” mean when you build the list from an API?

How do you discover election and campaign reporters in the Journalists API?

Which example election journalists resolve cleanly for a shortlist?

When should you use Journalists vs People vs Sources for election coverage?

The sections below answer each in order. Full journalist-parameter depth belongs with the Journalists API guide when it ships; this page owns election-desk discovery - not a Signals monitor playbook and not a left/right ideology roster.

Try it: Journalists sandbox · Docs: Entities · Pricing: API pricing

What “top journalists for elections” means here

This is a methodology-backed discovery list, not a permanent ranking or endorsement.

For the election beat we:

Search journalists with q values such as election or campaign, scoped with category=Politics (and often country=us).

Prefer profiles whose titles or top topics point at campaigns, polls, voting, Congress, or US politics - and whose topSources match national or election desks.

Resolve ambiguous names carefully: many common bylines return near-matches; keep the row whose title, Twitter handle, and sources fit the election desk you mean.

Apply resolved journalistId values on Articles when you need sample bylines or a lasting campaign feed.

Exact topic=Elections or topic=Campaigns filters can return empty sets depending on how journalist topTopics are populated. In practice, q + category is the reliable discovery path for this beat; treat topic filters as optional polish after you confirm live hits in the sandbox.

US elections recur on a fixed calendar (federal contests every two years, plus continuous primary, ballot, and voting-rules coverage). That scale is why a reusable reporter shortlist beats rebuilding name search every cycle.

How to discover election journalists in the Journalists API

On the Journalists API (/v1/journalists/all), start with a discovery query, then tighten.

Goal	Filters to try
Broad election desk	q=election, category=Politics
US-focused + active posters	Add country=us, minMonthlyPosts (e.g. 5)
Campaign trail language	q=campaign, category=Politics, country=us
Polling / analytics desks	q with polling language, category=Politics
Known byline	name (exact-ish resolve), then confirm title and topSources
Stable product filter	Copy id into Articles as journalistId

Useful result fields for shortlists: id, name, title, topSources, topTopics, topCategories, avgMonthlyPosts, and Twitter handle when present.

On Articles (/v1/all), pass one or more journalistId values to pull that byline’s coverage. Add q=election (or campaign / ballot language) when you want election-framed hits only.

Use excludeJournalistId when a syndication-heavy byline floods the feed. Parameter reference: Entities.

Example election journalist shortlist

Resolved from live Journalists lookups. Prefer the id column in products; re-resolve when titles or desks change.

National campaign and politics desks

Name	Desk cue (from profile)	Primary outlets (topSources)	journalistId
Maggie Haberman	Senior Political Correspondent	nytimes.com	b7cc246d2e7a470a90b81f3d4ccad2ca
Jonathan Swan	Politics reporter	nytimes.com	97ce96fa1e36456c8a5c88c02900224c
Katie Glueck	National political reporter	nytimes.com	fe243583d666442fb4ccd85e5aed6b06
Reid Epstein	Politics Reporter	nytimes.com	25cb2840e4174b4a9c5bb2b72c424cf8
Annie Karni	Congressional Correspondent	nytimes.com	713c41110d664d02b02f9468eaa165b7
Nick Corasaniti	Domestic politics / voting	nytimes.com	4e7f0207d5664ee184f0a9b516d61836
Nate Cohn	Polls / US politics analytics	nytimes.com	fd2f250b31414dd8bf7ecd64bd3c880c
Robert Costa	Chief Election and Campaign Correspondent	cbsnews.com	a1ed83f0e9024614af5a8ac75606e8f5
Kate Sullivan	Campaign Embed	bloomberg.com	2d98292d26314fd1bcbd0cb6b86aba76

Election-title and polling discovery hits

These appeared when searching journalists with q=election and category=Politics - strong title signals for an election roster:

Name	Desk cue (from profile)	Primary outlets (topSources)	journalistId
Helen Coster	U.S. Presidential Election Correspondent	reuters.com	0f31d31dfd66430195eb005f7c04ee7c
Stephanie Kelly	U.S. Presidential Election Correspondent	regional / wire syndication	14f953f977bb42f5bb83d78cd39aa3e7
Ariel Edwards-Levy	Editor, Polling and Election Analytics	cnn.com	cce8e73d74ca4d8faf7d795439f39961
Stephen Ohlemacher	Election Decision Editor	regional TV news sites	38b074d3c62f463ab7401131425fee4c
Katie Bernard	Election administration / suburban politics	inquirer.com	18c20d8ddfce494d9f07731449d67dae

Name search is noisy: common names return managers, local TV hosts, or near-spellings. Keep rows where title + topSources + Twitter agree with the election desk you intend - drop zero-activity or off-beat collisions.

Sample coverage by these bylines

After you resolve IDs, Articles filtered with journalistId plus q=election show how that byline’s election-framed copy looks in the index - useful as a pattern check, not as lasting newsjack content. Refresh samples when you ship the product; volumes and syndication domains change.

Continuous Signals watches for Capitol Hill and leadership entities are a different job from a journalist roster - keep this page on byline discovery.

When to use Journalists vs People vs Sources

Need	Use	Why
Who wrote the story	Journalists API + Articles journalistId / author	Bylines and reporter profiles
Who the story is about	People filters (personName, personWikidataId)	Candidates, officials, surrogates as entities
Which outlets to allow	Sources / source groups	Publisher inventory, not individual reporters
Campaign narrative momentum	Stories (optional)	Clusters across many bylines - link Stories guides, do not re-teach here

Journalists answer “whose byline”; People answer “who was mentioned”; Sources answer “which publisher.” Election products often need all three - but this page starts with the reporter list.

Election coverage scale at a glance

A few facts that explain why a reusable election journalist shortlist beats keyword-only alerts:

US federal elections land every two years, with primaries, ballot measures, and voting-rules fights filling the gaps - the campaign desk never fully goes quiet.

Polling, election administration, and national politics each produce different bylines; one q=election alert mixes them without telling you who wrote the piece.

In the Articles index for pubDate 2026-06-16 through 2026-07-16 (US sources): about 820,000 Politics-category articles, and about 134,000 Politics hits that also match election - enough volume that byline allowlists matter for outreach, citation, and product feeds.

In the same window, “White House” and Congress keyword lanes sit around 150,000 and 170,000 articles respectively - adjacent politics firehoses that election desks still collide with unless you filter on reporters, people, or sources.

Round large counts in product copy; re-run stats when you ship so the window stays current.

Key takeaways

Build election journalist lists with Journalists discovery (q + category=Politics), not keyword article search alone.

Resolve names carefully; store journalistId for stable Articles filters.

Mix national campaign desks with explicit election-title and polling profiles so the shortlist is not one outlet only.

Use People for candidates and officials; use Sources when the unit of filtering is the publisher.

Re-run discovery when desks change - titles and topSources drift between cycles.

Get started: Journalists sandbox · Entities · API pricing

How Monitor US Politics News

Oleksyj Mokrousov — Mon, 27 Jul 2026 14:02:59 +0000

Why teams monitor US politics news

Monitoring US politics news isn't difficult because there are too many articles - it's difficult because keywords fail. Search for "Congress" and you'll get foreign legislatures, sports teams, opinion columns, and photo captions. Meanwhile, the leadership announcements, committee votes, and White House decisions that actually matter disappear into the noise.

Teams building a durable washington politics news or capitol hill news watch usually ask:

How do you monitor US politics news?

How do you resolve White House and Congress leadership before filtering articles?

How do Articles API and Stories API recipes keep us government news and election coverage precise?

When should you use Signals vs Articles vs Stories for US politics?

The sections below answer each in order. Entity parameter depth lives in Entities; this page owns the US politics Signals + institution playbook.

Try it: perigon.io/home · Articles sandbox: sandbox · Entities docs: Entities · Pricing: Signals pricing

What “monitor US politics” means in practice

A continuous watch for us policy news is not the same as one search on election night. Signals keeps a briefing lane running while leadership, bills, and campaigns evolve. Articles pins specific people, topics, and US source/geography filters for product feeds. Stories groups reprints when a floor fight, White House announcement, or campaign spike floods outlets at once - use velocity when you care that a narrative is accelerating, not only that one URL appeared.

Trade policy, sanctions, and agency enforcement each deserve their own Monitor draft when that desk is the product; keep this page on federal politics institutions and leadership.

How to monitor US politics news with Signals with perigon.io

Open perigon.io/home and describe the watch in plain language. Signals turns that ask into a continuous briefing so you are not rebuilding the same political news monitoring query every morning.

Name the institutions (White House, House, Senate), the people who define the beat for your desk, and the output shape (bullets, risks first, nonpartisan summary). Refine after the first run: tighten to legislation vs campaign rhetoric, or to leadership-only mentions.

Copy-paste Signal prompts

White House and executive agenda

Monitor US White House and executive-branch coverage affecting domestic policy and Congress relations. Prefer major national publishers. Summarize in short bullets for a policy reader; flag contested claims and distinguish official statements from opinion columns.

Capitol Hill / Congress watch

Track US House and Senate news: floor votes, leadership statements, committee markups, and Speaker or Majority Leader mentions. Focus on legislation and procedural fights. Exclude sports “House” and foreign parliament noise unless clearly about the US Congress.

Leadership and campaign spillover

Watch news that meaningfully mentions US political leadership (President, Vice President, Speaker of the House). Ignore photo-caption name-checks and unrelated people with the same surname. Note interviews, conference cancellations, and intra-party schedule fights that change Capitol Hill narrative.

These prompts are evergreen: they describe ongoing beats, not a single week’s headlines. Swap or add leaders when your desk’s org chart changes - keep Signal wording on roles plus confirmed people IDs from the table below.

Resolve White House and Congress leadership before you filter

US politics monitoring works best when people are resolved first. Name search alone surfaces athletes, musicians, and family members with the same string.

Canonical people (from People lookup)

Role (evergreen)	Name	Use in filters	Resolved value
President of the United States	Donald Trump	personWikidataId	Q22686
Vice President of the United States	JD Vance	personWikidataId	Q28935729
Speaker of the House	Mike Johnson	personWikidataId	Q19880665

When you re-run People search for “Donald Trump,” keep Q22686 - not Donald Trump Jr. (Q3713655) or family matches. For “JD Vance,” keep Q28935729 (Vice President) - not unrelated JD / Vance hits. For “Mike Johnson,” keep Q19880665 (Speaker) - not hockey, music, or football collisions.

On the People API (/v1/people/all), refresh lookups when leadership changes; keep Signal prompts and article filters on these Wikidata IDs. Param reference: Entities.

Example coverage snapshot

Coverage pinned to these entities often looks like leadership schedule fights or Congress reacting to a White House policy frame - for example:

Article-style hits on Speaker-linked House lanes (e.g. House leaders backing a White House framework) from national or regional DC-facing publishers such as insidenova.com.

Story-style clusters where VP and House GOP calendars collide (e.g. a canceled House Republican Conference appearance tied to conference and election-integrity fights) with several outlets reprinting the same narrative.

Use overviews like those as pattern checks only - refresh samples when you build the product; do not treat one week’s cluster as lasting newsjack content.

Articles API recipes for White House, Congress, and elections

On the Articles API (/v1/all), pin people with personWikidataId rather than bare last-name q when you need white house news, congress news, or senate news without surname collisions.

Goal	Start with	Optional add-ons
Core us politics news / dc politics news	category or topic Politics; sourceCountry us when you want US publishers	excludeLabel for Opinion when you want harder news
White house news / president lane	personWikidataId Q22686	Short q for bill, veto, executive order when event type matters
VP / administration spillover	personWikidataId Q28935729	Combine with Politics category
House of representatives news / Speaker lane	personWikidataId Q19880665	q for House, Speaker, or conference when narrowing floor fights
Us election news / us campaign news	Politics topic + election / primary / ballot q	People pins for candidates your desk tracks; Stories when reprints explode
Fresh poll	addDateFrom from last checkpoint	sortBy on add date for ingest-style feeds

Prose example: pass personWikidataId set to Q22686 for the presidential lane, or Q19880665 when the Speaker defines the House story, add Politics category or topic, and poll with addDateFrom so each run only returns what is new since the last check. For partisan news filter workflows, prefer entity pins plus label excludes over hoping a keyword encodes “left” or “right.”

Public US left / right / center source groups can narrow publisher skew when your product needs a media-balance slice - discover and apply groups via Sources docs; do not rebuild group CRUD here.

Stories API recipes for politics story tracking

When floor fights, White House announcements, or campaign spikes reprint across dozens of outlets, Stories (/v1/stories/all) keeps politics story tracking on narratives instead of every mirror URL.

Pass the same personWikidataId values (for example Q28935729 for VP-centered clusters). Sort or filter by recent updates when you care that a Capitol Hill storyline is still moving. Full clustering and velocity theory lives in the Stories clustering guide - keep this page on US politics filters, not a second Stories textbook.

When to use Signals vs Articles vs Stories for US politics

Need	Prefer
Daily us politics news briefing without writing queries	Signals on perigon.io/home
Embed Capitol Hill feeds in a product	Articles API with personWikidataId + Politics filters
Leadership-sensitive policy or IR lanes	Confirmed Wikidata IDs above; optional Signal for narrative
“Is this Washington story accelerating?”	Stories with the same people / Politics scope
General entity param reference	Entities docs

US politics at a glance: why the beat stays noisy

A few scale facts that keep political news monitoring from sounding like a blank keyword alert:

A single Congress typically sees thousands of bills introduced; only a small fraction become law - the news firehose is the debate, not the final statutes.

Capitol Hill runs through hundreds of committees and subcommittees, each with its own markup, hearing, and leak cycle.

The executive branch issues dozens of directives and executive actions in busy stretches - White House messaging then collides with House and Senate reaction within hours.

Federal elections hit every two years (House all seats; Senate in classes), so us campaign news never fully leaves the wire even in “off” years.

The White House maintains a near-daily press briefing cadence - which is why white house news and capitol hill news need separate lanes in Signals and in API filters.

What that looks like in the index (30 days, pubDate 2026-06-15–2026-07-15, US sources): about 820,000 Politics-category articles; roughly 150,000 with “White House” in the query and 170,000 matching Congress; about 130,000 Politics hits that also mention elections. Leadership lanes show why person filters matter: on the order of 370,000 articles linked to the President (Q22686), about 42,000 for the Vice President (Q28935729), and about 11,000 for the House Speaker (Q19880665) in the same window - same beat, very different volumes, which is why Signals and API watches should separate White House, Congress, and leadership pins instead of one catch-all keyword.

Key takeaways

Monitor US politics news with Signals prompts on /home for continuous briefings, then mirror the beat in Articles and Stories.

Resolve leadership with Wikidata IDs: President Q22686, VP Q28935729, Speaker Q19880665 - skip surname collisions.

Combine people pins with Politics topic/category, US source scope, and addDateFrom for product feeds.

Use Stories for politics story tracking when reprints explode; keep velocity theory in the Stories guide.

Keep SEC, trade/tariffs, and single-company watches in their own Monitor drafts.

Get started: perigon.io/home · Entities docs · Stories clustering guide · Signals pricing

Build Custom News API Publisher Lists and Source Collections

Oleksyj Mokrousov — Mon, 27 Jul 2026 13:57:15 +0000

Custom publisher lists break when they live in every query

Hard-coding twenty domains into sources param works once. It fails when an analyst swaps a publisher, a competitor desk adds three trade outlets, or two products disagree on which regional papers belong in the allowlist. Teams then paste different domain strings into Articles, Headlines, Stories, and cron jobs - and alert quality drifts because the filter is no longer one object.

That is the job of a source groups API: turn a chosen publisher collection into a named, reusable filter. Perigon already ships public bundles (for example top100, top25finance, top50tech). This guide covers the source group CRUD surface for your own custom source lists, how private source groups and public source groups resolve, and how to apply them for cleaner monitoring.

What is a source groups API?

How do source groups improve repeatable filtering versus pasting sources param every time?

How do private and public source groups work for publisher collections?

How do custom publisher collections improve monitoring and alert quality?

Try it live: Sources sandbox · Read the docs: Sources and source groups · Compare plans: API pricing

What is a source groups API?

A source groups API manages named collections of publisher domains. Each group has a stable name (what you pass as sourceGroup on search), optional displayName and description, and a domains list. Once the group exists, article and story searches reference the name, not the raw domain string.

Perigon exposes this under /v1/api/sourceGroups:

Operation	Endpoint	Job
Create	POST /v1/api/sourceGroups	New org-owned group with name + domains (required); optional displayName, description
List	GET /v1/api/sourceGroups	Org-owned groups plus publicly visible bundles; filter by name or domain
Get	GET /v1/api/sourceGroups/{id}	One org-owned group by integer id
Resolve	GET /v1/api/sourceGroups/resolve	Map names → group records (private preferred)
Update	PATCH /v1/api/sourceGroups/{id}	Partial update of owned groups
Delete	DELETE /v1/api/sourceGroups/{id}	Remove an owned group

This page owns that lifecycle. Publisher discovery (find a domain, visits, paywall, geo) lives on the Sources API (/v1/sources/all) - see the News Source API post for the directory cookbook, and Sources docs. Vertical inventories like healthcare trade pubs or top25finance live in those compare posts, not here.

How source groups improve news filtering

Without groups, every feed embeds a domain allowlist. With groups, search params stay short and reusable publisher filters stay in one place.

Approach	What you maintain	Drift risk
Repeated source=a.com,b.com,...	Domain string in every client	High - each caller copies a slightly different list
Named sourceGroup=my-desk	One group record + search param	Low - patch the group; queries keep the same name

Typical flow:

1) Discover candidate domains with the Sources API (or Source Explorer) when you need metadata.

2) Create a custom source list with POST /v1/api/sourceGroups and your domains array (1–5000 domains).

3) Resolve or list by name when another service only has the label.

4) Apply sourceGroup on Articles (/v1/all), Headlines, Stories, or Sources to scope results to that collection.

5) On Articles, use excludeSourceGroup when you want everything except a noisy bundle.

You can still use bare source / excludeSource for one-off domain tweaks. Groups are for collections you will reuse.

Pass excludeSourceGroup when you need a publisher denylist bundle on Articles only. Stories and Sources accept sourceGroup for include-side scoping; Stories do not support group excludes the same way Articles do. For industry packs already published as public names, start there and customize privately - see the healthcare trade publications and top25finance posts for those inventories.

Private and public source groups for publisher collections

Public source groups are Perigon-maintained curated source bundles (for example top10, top100, top500English, top25crypto, top25finance, top50tech, top100sports, and US left / right / center packs). Anyone with API access can pass those names as sourceGroup. List can return publicly visible groups alongside your own.

Private source groups are created under the organization tied to your API key. Create, get-by-id, patch, and delete only apply to groups your org owns. That is where analyst approved sources, competitor publisher list subsets, and regional source collection forks belong.

Resolve is the important rule: GET /v1/api/sourceGroups/resolve with one or more name values returns, for each name, your organization's private group if one exists; otherwise the matching public group. That lets a product use a shared public label like top50tech until you create a private group with the same name - after which resolve (and your mental model for that workspace) prefers the private definition. Keep private names intentional so you do not shadow a public bundle by accident.

Workspace UI under Settings → Source Groups can create the same objects for teams that prefer a console; the API is the programmable path for CI and multi-product orgs. Long lists you cannot maintain yourself can also be requested from Perigon support - the same collection model applies.

How custom publisher collections improve monitoring and alert quality

Alerts and monitors fail noisily when the publisher set wanders. A stable group name is a contract between the research desk and the pipeline.

Pattern	Collection idea	Search habit
Analyst approved	Domains the desk signed off on	sourceGroup = private name on every poll
Competitor desk	Tier-1 + relevant trade outlets only	sourceGroup include, or Articles excludeSourceGroup for spam packs
Regional fork	Public national pack minus irrelevant wires	Private group copied from a public starting set, then patched
Product vs research	Two private names, same topic keywords	Same q / company filters; different sourceGroup

Updating domains is a PATCH on the group id, not a redeploy of every query string. List with domain when you need to find which workspace source groups already contain a publisher. Delete when a product is retired so resolve does not keep pointing at stale private names.

Inspection tip: to see membership of a named bundle without re-teaching Sources here, call Sources with sourceGroup set to that name - that is directory view of members. Lifecycle changes still go through /v1/api/sourceGroups.

Source group CRUD fields and list filters

Create body

Field	Required	Notes
name	Yes	Stable slug used as sourceGroup on search
domains	Yes	Array of publisher domains
displayName	No	Human label in UI
description	No	Desk notes / ownership

List query

Param	Role
name	Filter groups by name
domain	Find groups that include a domain
sortBy / sortOrder	Required sort controls on list
page / size	Pagination

Resolve query: name (up to 100 names) → private-first records.

Use cases

Analyst-approved allowlist

Create a private group with the domains research marked as trustworthy for a product. Poll Articles with that sourceGroup plus your topic or company filters. When analysts add a site, patch domains - alert jobs keep the same group name.

Competitor publisher list

Build a tight publisher allowlist for competitor coverage, or keep a wide search and attach excludeSourceGroup on Articles for bundles you never want in the feed. Persist the exclude name the same way you persist the include name.

Regional source collection

Start from a public national or language pack name for smoke tests, then create a private regional collection with only the markets you serve. Resolve tells services which definition wins for a given name in your org.

Industry packs

Pass public names such as top25finance or healthcareTradePublications when the maintained pack is enough. Domain-by-domain justification belongs in the vertical posts; this API topic stops at “create or resolve the collection, then apply the name.”

When to use groups vs Sources vs bare source

Need	Use
Find or rank publishers by visits, geo, paywall	Sources API (/v1/sources/all)
Reuse a domain set across products and jobs	Source Groups API + sourceGroup
One-off include or exclude of a few domains	source / excludeSource
Industry SERP + curated inventory write-up	Vertical trade-pub / finance posts
Narrative / velocity monitoring	Stories (and Breaking) guides - same sourceGroup name if helpful

Compose with other filters

sourceGroup is a publisher gate, not a topic engine. Stack it with q, company or people filters, dates (from / to / addDateFrom), taxonomy, category, and topic the same way you would with source. Keep this article’s examples group-centric; parameter cookbooks for entities and taxonomy stay in those pillar posts.

API plans

Source filtering and curated public groups are available across API plans; private group capacity and volume limits follow your tier. Confirm current limits on API pricing.

Key takeaways

The source groups API (/v1/api/sourceGroups) owns create, list, get, resolve, patch, and delete for custom source lists.

Resolve prefers your org’s private source group over a matching public source group for the same name.

Apply collections with sourceGroup (and Articles excludeSourceGroup) - do not paste long domain strings into every client.

Use Sources for publisher metadata; use vertical posts for industry domain inventories; use this page for source group CRUD and resolution rules.

Get started: Sources and source groups · API reference · Sources sandbox

Keyword vs Google Taxonomy: Fix Noisy Vertical News Alerts

Oleksyj Mokrousov — Sat, 25 Jul 2026 10:23:06 +0000

Your industry alert is still a string match

A “banking desk” built on q = bank will happily ingest river banks, blood banks, data banks, and robbery blotter. A “rock feed” on q = rock will mix geology, wrestling, and cocktail recipes with actual Rock Music coverage. The channel looks productive; the product is not on-vertical.

This page is a bakeoff diagnostic for noisy keyword desks. It is not the full Google taxonomy filter cookbook (exact path vs prefixTaxonomy, Stories, classify). That lives on Perigon’s News API filter by Google taxonomy guide - link out when you are ready to wire the params.

Why do vertical keywords inflate alerts?
How large are the gaps for bank, fund, and rock?
When should you use taxonomy vs Perigon category vs topic?
What bakeoff should you run before shipping a desk?

Why vertical keywords inflate alerts

Keywords match tokens. Vertical desks need aboutness. Google Content Category paths (V2) on Perigon articles describe industry and content family - Banking under Finance, Rock Music under Arts & Entertainment - so a filter can mean “this kind of story,” not “this substring appeared.”

Habit	What you get
q = bank / banking	Central banks, rivers, features named “bank,” crime, metaphors
q = fund	Mutual funds plus “fund a project,” fundraisers, verb uses
q = rock	Music plus geology, sports nicknames, food, idioms
Taxonomy path for the vertical	Articles classified into that Google hierarchy

You still stack dates, sources, and companies. The fix is choosing the right aboutness filter first.

Live bakeoff: bank, fund, rock (30 days)

Articles counts for pubDate 2026-06-25 through 2026-07-25 (round in product copy; huge open queries are order-of-magnitude):

Desk intent	Keyword filter	About how many	Taxonomy / structured filter	About how many
Banking vertical	q = bank	~988,000	taxonomy = /Finance/Banking/Other	~363,000
Banking (wordier keyword)	q = banking	~259,000	prefixTaxonomy = /Finance/Banking	~363,000
Funds vertical	q = fund	~695,000	taxonomy = /Finance/Investing/Funds	~398,000
Rock music vertical	q = rock	~341,000	taxonomy = /Arts & Entertainment/Music & Audio/Rock Music	~210,000

Read the table carefully. Taxonomy is not always the smallest number - q = banking (~259k) is below Banking taxonomy (~363k) because many banking stories never use the token “banking.” The failure mode is different: keywords miss on-vertical pieces and include off-vertical tokens. Taxonomy stays on the Google Banking branch either way.

Keyword bank (~988k) is still ~2.7× the Banking taxonomy slice - that gap is mostly noise and adjacent senses. Keyword fund (~695k) vs Funds path (~398k) shows the same pattern. Keyword rock (~341k) vs Rock Music (~210k) cuts a large geology/idiom/sports tail while keeping tour and album coverage the music desk wants.

For a wider finance firehose, prefixTaxonomy = /Finance was about 3.4M in the same window - useful as a branch monitor, not a tight desk. Pair a narrower leaf path when alerts must stay readable.

Taxonomy vs category vs topic (pick one job)

Perigon exposes three related dimensions. Mixing them up recreates keyword chaos with nicer names.

Filter	What it is	Use when
taxonomy / prefixTaxonomy	Google Content Category paths	Industry / content-family desks (Banking, Rock Music, Health Conditions)
category	Perigon broad themes (Finance, Tech, Health, …)	Fast dashboard buckets; e.g. category = Finance was ~3.5M in this window
topic	Granular Perigon topics	Storyline types - e.g. topic = Cryptocurrency ~187k vs q = cryptocurrency ~89k (topic can out-recall a thin keyword)

Rule of thumb: Google path when the desk is an industry tree; Perigon category for coarse theme chrome; topic when you need a named storyline slice. Stack carefully - do not OR three overlapping definitions of “finance” and call it precision. Deep param behavior stays on the taxonomy filter guide linked above.

Bakeoff checklist before you ship a vertical alert

Write the desk intent in one sentence (“Rock Music coverage,” not “anything with rock”).
Run q = token and the matching Google taxonomy (or prefixTaxonomy) for the same from/to window.
Spot-check twenty titles from each list - count off-vertical hits and obvious misses.
If the keyword is quieter but incomplete (like q = banking vs Banking path), prefer taxonomy and accept the larger on-vertical set.
Only then add source packs, companies, or labels - aboutness first, polish second.

Key takeaways

Vertical q filters are string matches; taxonomy paths are aboutness filters for industry desks.
Live gaps matter: bank ~988k vs Banking taxonomy ~363k; rock ~341k vs Rock Music ~210k (30 days ending 2026-07-25).
Quieter keywords are not always better - banking can under-recall vs the Banking path.
Use taxonomy for industry trees, category for broad themes, topic for granular storylines.