News

Get trending topics and entities

Returns trending aggregations across news articles. Analyze trends by source, category, topic, industry, or entity. Supports time bucketing, comparison windows, growth rate analysis, and percentile filtering. Maximum date range: 30 days.

post/v1/news/trends

Request

  • Base URL: https://api.apitube.io
  • URL: https://api.apitube.io/v1/news/trends
  • Auth: one of:
    • API key in header X-API-Key
    • API key in query parameter api_key

Request body

field'source.id' | 'category.id' | 'topic.id' | 'industry.id' | 'entity.id'

Comma-separated fields to aggregate (max 5). Required.

per_pageinteger

Number of results per field

offsetinteger

Offset for pagination

mincountinteger

Minimum article count for a value to be included

sort'count' | 'value' | 'growth_rate' | 'change' | 'trending_score'

Sort field (change and trending_score require compare=1)

order'asc' | 'desc'

Sort order

time_bucket'hour' | 'day' | 'week' | 'month'

Time bucket for time-series breakdown

trending'0' | '1'

Enable trending analysis with growth rate calculation

trending_daysinteger

Number of days for trending analysis window

compare'0' | '1'

Enable period comparison

compare_windowstring

Comparison window (required when compare=1). Examples: 24HOURS, 7DAYS, 1WEEK, 1w, 2m

percentileinteger

Filter results above this percentile

promptstring

Plain-language description of the news you want, e.g. "Elon Musk, Tesla, news for the last 10 days". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt).

querystring

Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.

article.idstring

Comma-separated article IDs (max 5)

titlestring

Search in article titles. Supports phrase search with proximity: "climate change"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110.

ignore.titlestring

Exclude articles containing this text in the title

title_starts_withstring

Filter articles whose title starts with the given text. Same 31-day window limit as title

title_ends_withstring

Filter articles whose title ends with the given text. Same 31-day window limit as title

title_patternstring

Filter articles whose title matches the given pattern. Same 31-day window limit as title

published_atstring

Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601

published_at.startstring

Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

published_at.endstring

End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

language.codestring

Comma-separated ISO 639-1 language codes (max 3)

ignore.language.codestring

Exclude articles in these languages (comma-separated, max 3)

source.country.codestring

Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)

ignore.source.country.codestring

Exclude sources from these countries (comma-separated, max 3)

source.rank.opr.mininteger

Minimum Open PageRank score

source.rank.opr.maxinteger

Maximum Open PageRank score

source.idstring

Comma-separated source IDs (max 3)

ignore.source.idstring

Exclude these source IDs (comma-separated, max 3)

source.domainstring

Comma-separated source domains (max 3)

ignore.source.domainstring

Exclude these source domains (comma-separated, max 3)

source.biasstring

Filter by media bias (comma-separated). Values: left, center, right

ignore.source.biasstring

Exclude sources with this media bias (comma-separated). Values: left, center, right

is_premium_source0 | 1

Filter by premium source status

is_verified_source0 | 1

Filter by verified source status

category.idstring

Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000

ignore.category.idstring

Exclude these categories (comma-separated, max 3)

topic.idstring

Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news

ignore.topic.idstring

Exclude these topics (comma-separated, max 3)

industry.idstring

Comma-separated industry IDs (max 3)

ignore.industry.idstring

Exclude these industries (comma-separated, max 3)

entity.idstring

Comma-separated entity IDs (max 3)

ignore.entity.idstring

Exclude these entity IDs (comma-separated, max 3)

entity.sentiment.polarity'positive' | 'negative' | 'neutral'

Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293.

entity.sentiment.score.minnumber

Minimum sentiment score toward the entity

entity.sentiment.score.maxnumber

Maximum sentiment score toward the entity

person.namestring

Filter by person name (comma-separated, max 3)

ignore.person.namestring

Exclude articles mentioning these persons (comma-separated, max 3)

organization.namestring

Filter by organization name (comma-separated, max 3)

ignore.organization.namestring

Exclude articles mentioning these organizations (comma-separated, max 3)

location.namestring

Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218

ignore.location.namestring

Exclude articles mentioning these locations (comma-separated, max 3)

brand.namestring

Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222

ignore.brand.namestring

Exclude articles mentioning these brands (comma-separated, max 3)

disaster.namestring

Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224

ignore.disaster.namestring

Exclude articles mentioning these disasters (comma-separated, max 3)

disease.namestring

Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226

ignore.disease.namestring

Exclude articles mentioning these diseases (comma-separated, max 3)

event.namestring

Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228

ignore.event.namestring

Exclude articles mentioning these events (comma-separated, max 3)

sport.namestring

Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250

ignore.sport.namestring

Exclude articles mentioning these sports (comma-separated, max 3)

event.typestring

Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche

event.category'business' | 'society' | 'environment'

Filter by event category

ignore.event.typestring

Exclude these event types (comma-separated, max 5)

sentiment.overall.scorenumber

Exact overall sentiment score

sentiment.overall.score.minnumber

Minimum overall sentiment score

sentiment.overall.score.maxnumber

Maximum overall sentiment score

sentiment.overall.polarity'positive' | 'negative' | 'neutral'

Overall sentiment polarity

sentiment.title.scorenumber

Exact title sentiment score

sentiment.title.score.minnumber

Minimum title sentiment score

sentiment.title.score.maxnumber

Maximum title sentiment score

sentiment.title.polarity'positive' | 'negative' | 'neutral'

Title sentiment polarity

sentiment.body.scorenumber

Exact body sentiment score

sentiment.body.score.minnumber

Minimum body sentiment score

sentiment.body.score.maxnumber

Maximum body sentiment score

sentiment.body.polarity'positive' | 'negative' | 'neutral'

Body sentiment polarity

sentiment.mixed0 | 1

Filter for mixed sentiment (title polarity != body polarity)

sentiment.consistent0 | 1

Filter for consistent sentiment (title polarity == body polarity)

is_clickbait0 | 1

Filter by clickbait detection

sentiment_gap.minnumber

Minimum sentiment gap between title and body

sentiment_gap.maxnumber

Maximum sentiment gap between title and body

media.images.countinteger

Exact number of images

media.images.count.mininteger

Minimum number of images

media.images.count.maxinteger

Maximum number of images

media.images.width.mininteger

Minimum image width in pixels

media.images.width.maxinteger

Maximum image width in pixels

media.images.height.mininteger

Minimum image height in pixels

media.images.height.maxinteger

Maximum image height in pixels

media.videos.countinteger

Exact number of videos

media.videos.count.mininteger

Minimum number of videos

media.videos.count.maxinteger

Maximum number of videos

has_image0 | 1

Filter articles with/without images

has_video0 | 1

Filter articles with/without videos

has_hq_images0 | 1

Filter articles with high-quality images (>= 1200px width)

is_media_rich0 | 1

Filter articles with both images and videos

is_landscape_media0 | 1

Filter articles with landscape-oriented media

is_portrait_media0 | 1

Filter articles with portrait-oriented media

has_multiple_images0 | 1

Filter articles with 2+ images

has_fullhd_images0 | 1

Filter articles with Full HD images (>= 1920px width)

has_4k_images0 | 1

Filter articles with 4K images (>= 3840px width)

has_mobile_optimized_images0 | 1

Filter articles with mobile-optimized images (320-800px width)

is_instagram_ready0 | 1

Filter articles with Instagram-ready images (>= 1080px + aspect ratio)

is_twitter_card_ready0 | 1

Filter articles with Twitter Card-ready images (>= 800px + landscape)

has_consistent_image_sizes0 | 1

Filter articles with consistent image dimensions

has_thumbnail0 | 1

Filter articles with thumbnail images (<= 300px width)

has_social_share_image0 | 1

Filter articles with social share images (>= 1200x630px)

has_mixed_media0 | 1

Filter articles with both image and video media types

readability.fk_gradenumber

Exact Flesch-Kincaid grade level

readability.fk_grade.minnumber

Minimum Flesch-Kincaid grade level

readability.fk_grade.maxnumber

Maximum Flesch-Kincaid grade level

readability.easenumber

Exact Flesch Reading Ease score

readability.ease.minnumber

Minimum Flesch Reading Ease score

readability.ease.maxnumber

Maximum Flesch Reading Ease score

readability.arinumber

Exact Automated Readability Index

readability.ari.minnumber

Minimum Automated Readability Index

readability.ari.maxnumber

Maximum Automated Readability Index

readability.difficulty'beginner' | 'intermediate' | 'advanced' | 'expert'

Difficulty level

readability.audience'children' | 'general' | 'professional' | 'academic'

Target audience

readability.ageinteger

Exact reading age

readability.age.mininteger

Minimum reading age

readability.age.maxinteger

Maximum reading age

is_easy_read0 | 1

Filter for easy-to-read articles (Flesch Reading Ease >= 60)

is_difficult_read0 | 1

Filter for difficult-to-read articles (Flesch Reading Ease < 40)

read_timeinteger

Exact read time in minutes

read_time.mininteger

Minimum read time in minutes

read_time.maxinteger

Maximum read time in minutes

is_long_read0 | 1

Filter for long reads (>= 5 minutes)

is_short_read0 | 1

Filter for short reads (< 3 minutes)

is_quick_read0 | 1

Filter for quick reads (<= 2 minutes)

is_medium_read0 | 1

Filter for medium-length reads (3-7 minutes)

is_deep_dive0 | 1

Filter for deep dives (>= 10 minutes)

location.bboxstring

Bounding box: minLat,maxLat,minLng,maxLng

has_location_geo0 | 1

Filter articles with/without geo-location data

location.latnumber

Latitude for radius search

location.lngnumber

Longitude for radius search

location.radiusnumber

Search radius in kilometers (requires location.lat and location.lng)

location.radius.minnumber

Minimum distance from point in km

is_duplicate0 | 1

Filter duplicate/unique articles

is_paywall0 | 1

Filter paywalled articles

is_breaking0 | 1

Filter breaking news articles

is_high_quality0 | 1

Filter high-quality articles (not duplicate, rank >= 5, has images, has author)

author.idstring

Comma-separated author IDs (max 3)

ignore.author.idstring

Exclude these author IDs (comma-separated, max 3)

author.namestring

Filter by author name (comma-separated, max 3)

ignore.author.namestring

Exclude articles by these authors (comma-separated, max 3)

has_author0 | 1

Filter articles with/without author

api_keystring

API key (alternative to X-API-Key header)

Example request

{
  "query": "bitcoin AND NOT (etf OR futures)",
  "article.id": "12345",
  "published_at": "2025-01-15",
  "published_at.start": "2025-01-01",
  "published_at.end": "2025-01-31",
  "language.code": "en",
  "ignore.language.code": "zh,ar",
  "source.country.code": "us",
  "ignore.source.country.code": "us",
  "source.id": "100",
  "source.domain": "nytimes.com",
  "source.bias": "left",
  "ignore.source.bias": "right",
  "category.id": "medtop:04000000",
  "topic.id": "industry.technology_news",
  "industry.id": "1",
  "entity.id": "12345",
  "person.name": "Elon Musk",
  "organization.name": "Google",
  "location.name": "New York City",
  "event.type": "ipo",
  "location.bbox": "40.0,41.0,-74.5,-73.5"
}

Response

Successful response with trend data

status'ok'
fieldstring

Aggregated field (single-field request)

fieldsstring[]

Aggregated fields (multi-field request)

per_pageinteger

Results per field

offsetinteger

Pagination offset

total_countinteger

Distinct values count (single-field request)

total_articlesinteger

Total matching articles (single-field request)

sortstring

Sort field used

order'asc' | 'desc'

Sort order used

mincountinteger

Minimum article count threshold used

percentileinteger

Percentile filter (present when percentile is set)

time_bucketstring

Time bucket (present when time_bucket is set)

compare_windowstring

Comparison window (present when compare=1)

trending_daysinteger

Trending window in days (present when trending=1)

cachedboolean

Whether the result was served from cache

request_idstring

Changes

No recorded changes to this operation across all 1 revision of this API.