API Response Structure

Use this reference to read API responses and check the meaning and possible values of each field.

General response structure

The standard JSON response has this format:

json

{
    "status": "ok",
    "limit": 1,
    "path": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1",
    "page": 1,
    "has_next_pages": true,
    "next_page": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&page=2",
    "has_previous_page": false,
    "previous_page": "",
    "export": {
        "json": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=json",
        "xlsx": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=xlsx",
        "csv": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=csv",
        "tsv": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=tsv",
        "xml": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=xml",
        "rss": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=rss",
        "parquet": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=parquet",
	    "jsonl": "https://api.apitube.io/v1/news/everything?api_key=API_KEY&per_page=1&export=jsonl"
    },
    "request_id": "1044de7a-a39d-463c-b443-1d9141f7babe",
    "results": [
        // Array of articles
    ]
}

Main response fields

Field	Type	Description
`status`	string	Request status. Possible values: "ok" (request successful) or "error" (an error occurred).
`limit`	integer	Number of results per page.
`path`	string	Full URL of the current API request, including all request parameters.
`page`	integer	Current page of results.
`has_next_pages`	boolean	`true` if another page of results is available.
`next_page`	string	Full URL to get the next page of results. Empty string if `has_next_pages` is false.
`has_previous_page`	boolean	`true` if a previous page of results is available.
`previous_page`	string	Full URL to get the previous page of results. Empty string if `has_previous_page` is false.
`export`	object	URLs to download results as JSON, JSONL, CSV, TSV, XLSX, XML, RSS or Parquet.
`request_id`	string	Request ID for tracking and debugging.
`meta`	object	Warnings or details about a `prompt`, when available — see The meta object.
`results`	array	Articles returned by the request.

The meta object

A successful response may include meta with warnings or details about a prompt. Articles remain in results with the same format.

Field	Type	Appears when
`meta.prompt`	object	The request used the `prompt` parameter.
`meta.warnings`	array	The API limited the search range. For example, a title search without dates covers the last 31 days (`ER0366`).

meta.prompt

json

{
    "meta": {
        "prompt": {
            "text": "Elon Musk and Tesla news for the last 10 days",
            "applied": {
                "person.name": "Elon Musk",
                "organization.name": "Tesla",
                "published_at.start": "NOW-10DAY"
            },
            "ignored": [
                { "field": "topic.id", "value": "robotaxi", "reason": "not_found" }
            ],
            "cached": false
        }
    }
}

Field	Type	Description
`text`	string	Your prompt, with spaces removed from the beginning and end.
`applied`	object	The parameters the prompt was translated into. This is the request that actually ran.
`ignored`	array	Values that were understood but not used. Each item has `field`, `value` and `reason`.
`cached`	boolean	`true` when the API reused an earlier interpretation of the same prompt, so no translation fee was charged.

meta.prompt is not returned by the SSE stream (/v1/news/stream), which has no JSON response. The WebSocket stream returns the same information in the filters object of its subscribed message. Full reference: Natural Language Search.

meta.warnings

json

{
    "meta": {
        "warnings": [
            {
                "code": "ER0366",
                "message": "published_at window defaulted to the last 31 days for title search. Pass published_at.start / published_at.end to pick a different 31-day window.",
                "links": {
                    "about": "https://docs.apitube.io/platform/news-api/http-response-codes"
                }
            }
        ]
    }
}

Warnings arrive with HTTP 200. For exports, the x-query-window-clamped response header reports when the title-search window was limited. See HTTP Response Codes.

Article object fields

Each article in the results array has the following structure:

json

{
    "id": "Unique article ID",
    "href": "URL of the original article",
    "published_at": "Publication date and time in ISO 8601 format",
    "title": "Article title",
    "description": "Brief article description",
    "body": "Full article text",
    "body_html": "Full article text with HTML formatting",
    "language": "Article language (ISO 639-1 code)",
    "translations": {
        "en": {
            "title": "Article title translated to English",
            "description": "Article description translated to English"
        }
    },
    "author": {
        "id": "Author ID",
        "name": "Author name"
    },
    "image": "URL of the main article image",
    "categories": [
        {
            "id": "Category ID",
            "name": "Category name",
            "score": "Category relevance score for the article",
            "taxonomy": "Category taxonomy name",
            "links": {
                "self": "URL to get information about the category"
            }
        }
    ],
    "topics": [
        {
            "id": "Topic ID",
            "name": "Topic name",
            "score": "Topic relevance score for the article",
            "links": {
                "self": "URL to get information about the topic"
            }
        }
    ],
    "industries": [
        {
            "id": "Industry ID",
            "name": "Industry name",
            "links": {
                "self": "URL to get information about the industry"
            }
        }
    ],
    "entities": [
        {
            "id": "Entity ID",
            "name": "Entity name",
            "type": "Entity type (person, location, organization, brand, product, natural-disaster, disease, event, sport, unknown)",
            "links": {
                "self": "URL to get information about the entity",
                "wikipedia": "Link to Wikipedia article",
                "wikidata": "Link to entity in Wikidata"
            },
            "frequency": "Frequency of entity mentions in the article",
            "sentiment": {
                "score": "Sentiment score toward this entity (-1 to 1)",
                "polarity": "Sentiment polarity toward this entity (positive, negative, neutral)",
                "mentions": "Per-mention polarity counts (positive, neutral, negative)"
            },
            "title": {
                "pos": "Array of entity mention positions in the title"
            },
            "body": {
                "pos": "Array of entity mention positions in the article body"
            },
            "metadata": "Additional entity information (varies by entity type)"
        }
    ],
    "source": {
        "id": "Source ID",
        "domain": "Source domain",
        "home_page_url": "URL of the source homepage",
        "type": "Source type (news, blog, etc.)",
        "bias": "Source bias",
        "rankings": {
            "opr": "Source ranking"
        },
        "location": {
            "country_name": "Source country name",
            "country_code": "Source country code (ISO 3166-1 alpha-2)"
        },
        "favicon": "Source favicon URL"
    },
    "sentiment": {
        "overall": {
            "score": "Overall article sentiment score",
            "polarity": "Textual representation of sentiment (positive, negative, neutral)"
        },
        "title": {
            "score": "Title sentiment score",
            "polarity": "Textual representation of title sentiment"
        },
        "body": {
            "score": "Article body sentiment score",
            "polarity": "Textual representation of body sentiment"
        }
    },
    "summary": [
        {
            "sentence": "Key sentence from the article",
            "sentiment": {
                "score": "Sentence sentiment score",
                "polarity": "Textual representation of sentiment"
            }
        }
    ],
    "keywords": "Array of article keywords",
    "links": [
        {
            "url": "URL mentioned in the article",
            "type": "Link type (link, etc.)"
        }
    ],
    "media": [
        {
            "url": "Media file URL",
            "type": "Media file type (image, video, etc.)"
        }
    ],
    "locations_mentioned": [
        {
            "name": "Location name",
            "country": "ISO 3166-1 alpha-2 country code",
            "lat": "Latitude (number or null)",
            "lng": "Longitude (number or null)",
            "type": "Location type (unknown if not classified)"
        }
    ],
    "readability": {
        "flesch_kincaid_grade": "Flesch-Kincaid grade level",
        "flesch_reading_ease": "Flesch reading ease score",
        "automated_readability_index": "Automated Readability Index (ARI)",
        "difficulty_level": "Difficulty level (beginner, intermediate, advanced, expert, unknown)",
        "target_audience": "Target audience (children, general, professional, academic, unknown)",
        "reading_age": "Estimated reading age",
        "avg_words_per_sentence": "Average words per sentence",
        "avg_syllables_per_word": "Average syllables per word"
    },
    "story": {
        "id": "Story ID (equal to the article id)",
        "uri": "URL to get information about the story"
    },
    "shares": {
        "total": "Total number of shares across all platforms",
        "facebook": "Number of Facebook shares",
        "twitter": "Number of Twitter/X shares",
        "reddit": "Number of Reddit shares"
    },
    "is_duplicate": "Flag indicating if the article is a duplicate",
    "is_free": "Flag indicating if the article is freely available (not behind paywall)",
    "is_breaking": "Flag indicating if the article is breaking news",
    "read_time": "Estimated reading time in minutes",
    "sentences_count": "Number of sentences in the article",
    "paragraphs_count": "Number of paragraphs in the article",
    "words_count": "Number of words in the article",
    "characters_count": "Number of characters in the article"
}

Article field reference

Field	Type	Description
`id`	integer	Unique article ID.
`href`	string	URL of the original article.
`published_at`	string	Date and time of article publication in ISO 8601 format.
`title`	string	Article headline.
`description`	string	Short article summary. May be absent.
`body`	string	Full article text without HTML tags.
`body_html`	string	Full article text with HTML formatting. May be absent for some articles.
`language`	string	Article language in ISO 639-1 format (two-letter code).
`translations`	object	English translations of the title and description in `translations.en.title` and `translations.en.description`. The object is always present. Both fields are `null` for English articles and languages without translation support. The body is not translated.
`author`	object	Author details. `id` may be `null` when unavailable.
`image`	string	URL of the main article image. May be absent for some articles.
`categories`	array	Categories assigned to the article.
`topics`	array	Topics related to the article, with relevance scores.
`industries`	array	Industries related to the article.
`entities`	array	People, places, organizations and other entities mentioned in the article.
`locations_mentioned`	array	Geographic locations mentioned in the article (`name`, `country`, `lat`, `lng`, `type`).
`source`	object	Publisher details.
`sentiment`	object	Tone of the article.
`summary`	array	Key sentences from the article, each with its sentiment.
`readability`	object	Readability metrics (Flesch-Kincaid grade, reading ease, ARI, difficulty level, target audience, reading age, avg words per sentence, avg syllables per word).
`keywords`	array	Keywords found in the article.
`links`	array	URLs mentioned in the article, with their link types.
`media`	array	Images and videos associated with the article, with their URLs and types.
`story`	object	The article's story ID (`id`) and API URL (`uri`).
`shares`	object	Share counts by social media platform.
`is_duplicate`	boolean	`true` if the article duplicates another article.
`is_free`	boolean	`true` if the article can be read without paying.
`is_breaking`	boolean	`true` if the article is breaking news.
`read_time`	integer	Estimated reading time in minutes.
`sentences_count`	integer	Number of sentences in the article.
`paragraphs_count`	integer	Number of paragraphs in the article.
`words_count`	integer	Number of words in the article.
`characters_count`	integer	Number of characters in the article.

Nested objects

Category object

json

{
    "id": 258,
    "name": "exporting",
    "score": 0.6,
    "taxonomy": "iptc_mediatopics",
    "links": {
        "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:20000366"
    }
}

Field	Type	Description
`id`	integer	Unique category ID.
`name`	string	Category name.
`score`	float	Category relevance score for the article (from 0 to 1).
`taxonomy`	string	Category system this category belongs to.
`links`	object	Links related to the category.

Topic object

json

{
    "id": "market_news.commodities.potash",
    "name": "Potash Market News",
    "score": 0.2,
    "links": {
        "self": "https://api.apitube.io/v1/news/topic/market_news.commodities.potash"
    }
}

Field	Type	Description
`id`	string	Unique topic ID.
`name`	string	Topic name.
`score`	float	Topic relevance score for the article (from 0 to 1).
`links`	object	Links related to the topic.

Industry object

json

{
    "id": 1067,
    "name": "Sporting event",
    "links": {
        "self": "https://api.apitube.io/v1/news/industry/1067"
    }
}

Field	Type	Description
`id`	integer	Unique industry ID.
`name`	string	Industry name.
`links`	object	Links related to the industry.

Entity object

json

{
    "id": 1034399,
    "name": "Germany",
    "type": "location",
    "links": {
        "self": "https://api.apitube.io/v1/news/entity/1034399",
        "wikipedia": "https://en.wikipedia.org/wiki/Germany",
        "wikidata": "https://www.wikidata.org/wiki/Q183"
    },
    "frequency": 3,
    "sentiment": {
        "score": -0.42,
        "polarity": "negative",
        "mentions": {
            "positive": 1,
            "neutral": 0,
            "negative": 2
        }
    },
    "title": {
        "pos": [{
            "start": 7,
            "end": 14
        }]
    },
    "body": {
        "pos": [
            {
                "start": 113,
                "end": 120
            },
            {
                "start": 852,
                "end": 859
            }
        ]
    },
    "metadata": {
        "name": "Germany",
        "type": "country",
        "aliases": ["Federal Republic of Germany"],
        "country": {
            "code": "DE",
            "name": "Germany"
        },
        "full_name": "Germany, Germany",
        "is_capital": false,
        "population": 83577140,
        "coordinates": {
            "lat": 51,
            "lng": 10
        },
        "description": "Country in Central Europe"
    }
}

Field	Type	Description
`id`	integer	Unique entity ID.
`name`	string	Entity name.
`type`	string	Entity type: `person`, `location`, `organization`, `brand`, `product`, `natural-disaster`, `disease`, `event`, `sport` or `unknown`. Name filters are available for eight types: `person.name`, `location.name`, `organization.name`, `brand.name`, `disaster.name`, `disease.name`, `event.name` and `sport.name`. Use `entity.id` for `product` or `unknown`. There is no `product.name` filter; that parameter is ignored.
`links`	object	Links to API, Wikipedia and Wikidata pages about the entity.
`frequency`	integer	Number of times the entity is mentioned in the article.
`sentiment`	object	Tone toward this entity across all its mentions: `score` (-1 to 1), `polarity` (`positive`/`negative`/`neutral`), and `mentions` (counts of `positive`, `neutral` and `negative` mentions).
`title`	object	Positions where the entity appears in the article title.
`body`	object	Positions where the entity appears in the article body.
`metadata`	object	Entity details; available fields depend on the entity type.

The fields in entity metadata depend on type:

Person: name, title, gender, aliases, bio_summary, nationality, organization, date_of_birth, social_profiles, is_real_person, is_public_figure, public_profile_url.
Location: full_name, country, coordinates, population, is_capital, description.
Organization or brand: description, website_url, logo_url, brand_owner, category, subcategory.

A field with no value is null. Handle this in your code.

Source object

json

{
    "id": 4232,
    "domain": "newsbytesapp.com",
    "home_page_url": "https://www.newsbytesapp.com",
    "type": "news",
    "bias": "right",
    "rankings": {
        "opr": 5
    },
    "location": {
        "country_name": "India",
        "country_code": "in"
    },
    "favicon": "https://www.google.com/s2/favicons?domain=https://www.newsbytesapp.com"
}

Field	Type	Description
`id`	integer	Unique source ID.
`domain`	string	Source domain.
`home_page_url`	string	URL of the source homepage.
`type`	string	Source type (e.g., "news", "blog").
`bias`	string	Source bias (e.g., "left", "right", "center").
`rankings`	object	Source ratings and metrics.
`location`	object	Publisher location.
`favicon`	string	URL of the source favicon.

Author object

json

{
    "id": 5678,
    "name": "John Smith"
}

Field	Type	Description
`id`	integer	Author ID, or null when unavailable.
`name`	string	Author name, or an empty string when unavailable.

Sentiment object

json

{
    "overall": {
        "score": -0.01,
        "polarity": "neutral"
    },
    "title": {
        "score": -0.09,
        "polarity": "negative"
    },
    "body": {
        "score": 0.07,
        "polarity": "positive"
    }
}

Field	Type	Description
`overall`	object	Tone of the article as a whole.
`title`	object	Tone of the article title.
`body`	object	Tone of the article body.

Each sentiment object contains:

score (float): a number from -1 to 1. Negative numbers mean negative sentiment; positive numbers mean positive sentiment.
polarity (string): the sentiment label: "positive", "negative" or "neutral".

Summary object

json

{
    "sentence": "an official said, highlighting the importance of this European nation in India",
    "sentiment": {
        "score": 0.17,
        "polarity": "positive"
    }
}

Field	Type	Description
`sentence`	string	Key sentence extracted from the article.
`sentiment`	object	Tone of this sentence.

Story object

json

{
    "id": 3019419820,
    "uri": "https://api.apitube.io/v1/news/story/3019419820"
}

Field	Type	Description
`id`	integer	Currently the same as the article's own `id`. There is no separate ID for the group of related articles.
`uri`	string	API URL for the story's details, using the article `id`.

Shares object

json

{
    "total": 288,
    "facebook": 149,
    "twitter": 74,
    "reddit": 65
}

Field	Type	Description
`total`	integer	Total number of shares across all platforms.
`facebook`	integer	Number of Facebook shares.
`twitter`	integer	Number of Twitter/X shares.
`reddit`	integer	Number of Reddit shares.

Links object

json

{
    "url": "https://www.newsbytesapp.com/news/world/belgium",
    "type": "link"
}

Field	Type	Description
`url`	string	URL mentioned in the article.
`type`	string	Link type (typically "link").

Media object

json

{
    "url": "https://i.cdn.newsbytesapp.com/images/l82720260111162041.jpeg",
    "type": "image"
}

Field	Type	Description
`url`	string	Media file URL.
`type`	string	Media file type (e.g., "image", "video").

Error response

If a request fails, check the HTTP status and the error details. For example, an authentication error returns 401:

json

{
  "status": 401,
  "code": "ER0175",
  "message": "Your API key is invalid or missing.",
  "links": {
      "about": "https://docs.apitube.io/platform/news-api/http-response-codes"
  }
}

Field	Type	Description
`status`	integer	HTTP status code of the error.
`code`	string	Error identifier for handling errors in your code.
`message`	string	Human-readable error message.
`links`	object	Links to documentation about the error.

Error codes

Code	HTTP status	Description
`invalid_api_key`	401	Invalid or missing API key.
`unauthorized`	401	The API key does not have permission for this request.
`quota_exceeded`	429	Request limit exceeded.
`invalid_parameter`	400	Invalid parameter value.
`missing_parameter`	400	Missing required parameter.
`internal_error`	500	Internal server error.

Pagination

Results are split into pages. The first request returns page 1. Use page to choose another page and per_page to set its size. The response's limit shows the number of items per page.

Example of pagination request:

text

https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20

Response with pagination information:

json

{
  "status": "ok",
  "limit": 20,
  "path": "https://api.apitube.io/v1/news/everything?title=technology&page=2&per_page=20",
  "page": 2,
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?title=technology&page=3&per_page=20",
  "has_previous_page": true,
  "previous_page": "https://api.apitube.io/v1/news/everything?title=technology&page=1&per_page=20",
  "results": [
    // Article objects
  ]
}

Trends endpoint response structure

The /v1/news/trends response groups counts by the fields you request. Its format depends on whether you choose one field or several.

Single field response

With one field, trends is an array:

json

{
    "status": "ok",
    "field": "entity.id",
    "per_page": 10,
    "offset": 0,
    "total_count": 1500,
    "total_articles": 45000,
    "sort": "count",
    "order": "desc",
    "mincount": 1,
    "trends": [
        {
            "value": {
                "id": 1034399,
                "name": "Germany",
                "type_id": 2,
                "wikidata_id": "Q183"
            },
            "count": 523,
            "percentage": 1.16,
            "growth_rate": 2.5
        }
    ],
    "request_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6"
}

Multiple fields response

With several comma-separated fields, results are grouped by field name. Each field has its own total_count and total_articles:

json

{
    "status": "ok",
    "fields": ["entity.id", "category.id"],
    "per_page": 10,
    "offset": 0,
    "sort": "count",
    "order": "desc",
    "mincount": 1,
    "trends": {
        "entity.id": {
            "trends": [...],
            "total_count": 1500,
            "total_articles": 45000
        },
        "category.id": {
            "trends": [...],
            "total_count": 200,
            "total_articles": 45000
        }
    },
    "request_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6"
}

Trends response fields

Field	Type	Description
`status`	string	Request status ("ok" or "error").
`field`	string	The requested field (single field mode only).
`fields`	array	Requested fields, present only when you request several fields.
`per_page`	integer	Number of trends per page.
`offset`	integer	Number of trends to skip.
`total_count`	integer	Total number of unique values for the field.
`total_articles`	integer	Sum of `count` for all values of the requested field. Used to calculate `percentage`. For `source.id`, each article has one value, so this is also the article count. For `category.id`, `topic.id`, `industry.id` and `entity.id`, an article is counted once for each value it contains. The total can therefore exceed the number of articles.
`sort`	string	Sort field used ("count", "value", "growth_rate"; "change", "trending_score" with compare=true).
`order`	string	Sort order ("asc" or "desc").
`mincount`	integer	Minimum article count required for a trend.
`trends`	array/object	With one field, an array of trends. With several fields, an object keyed by field name.
`request_id`	string	Unique request ID.
`percentile`	integer	Percentile filter applied (optional, 1-100).
`time_bucket`	string	Interval used for grouping counts: hour, day, week or month (optional).
`compare_window`	string	Period used for the comparison (optional, for example "7DAYS").
`trending_days`	integer	Number of days used for trending calculation (optional, 7-30).
`cached`	boolean	Whether the API reused a previously saved response (optional).

Trend object structure

Each trend object in the trends array contains:

json

{
    "value": {
        "id": 1034399,
        "name": "Germany",
        "type_id": 2,
        "wikidata_id": "Q183"
    },
    "count": 523,
    "percentage": 1.16,
    "growth_rate": 2.5,
    "previous_count": 400,
    "change_absolute": 123,
    "change_percent": 30.75,
    "trending_score": 1.85,
    "trending_history": {
        "2024-01-01": 10,
        "2024-01-02": 15,
        "2024-01-03": 25
    }
}

Field	Type	Description
`value`	object/mixed	The field value, with details when available. See the table below.
`count`	integer	Number of articles containing this value.
`percentage`	float	Percentage of total articles (0-100).
`growth_rate`	float	Number of articles per hour (`null` when unavailable).
`previous_count`	integer	Count in previous period (only with `compare=true`).
`change_absolute`	integer	Absolute change from previous period (only with `compare=true`).
`change_percent`	float	Percentage change from previous period (only with `compare=true`).
`trending_score`	float	Score comparing recent article counts with the historical average (only with `trending=true`).
`trending_history`	object	Daily counts for trending period (only with `trending=true`).

Trend object with time_bucket

With time_bucket, each trend includes counts by period. Values are returned as IDs without names or other metadata:

json

{
    "value": 1034399,
    "buckets": {
        "2024-01-15": 100,
        "2024-01-16": 150,
        "2024-01-17": 200
    },
    "total": 450
}

Field	Type	Description
`value`	mixed	The raw field value (ID). With `time_bucket`, names and other details are omitted.
`buckets`	object	Count for each time interval. Keys are dates formatted for the selected interval.
`total`	integer	Total count across all time intervals.

Date formats used as interval keys:

hour: "2024-01-15 14:00"
day: "2024-01-15"
week: "2024-01-15" (start of week)
month: "2024-01"

Value details by field

The details returned in value depend on the field you request:

Field	Value format
`entity.id`	`{ id, name, type_id, wikidata_id }`
`category.id`	`{ id, name, taxonomy }`
`topic.id`	`{ id, name }`
`industry.id`	`{ id, name }`
`source.id`	`{ id, name, domain }`

Trends request parameters

Parameter	Type	Values	Default
`field`	string	`source.id`, `category.id`, `topic.id`, `industry.id`, `entity.id` (comma-separated, max 5)	required
`sort`	string	`count`, `value`, `growth_rate` (+ `change`, `trending_score` with compare=true)	`count`
`order`	string	`asc`, `desc`	`desc`
`per_page`	integer	1-100	10
`offset`	integer	>= 0	0
`mincount`	integer	1-10000	1
`time_bucket`	string	`hour`, `day`, `week`, `month` (anything else → `400 ER0308`)	-
`compare`	boolean	`true`, `false`	`false`
`compare_window`	string	`24HOURS`, `7DAYS`, `1WEEK`, `2m`, etc.	required if compare=true
`trending`	boolean	`true`, `false`	`false`
`trending_days`	integer	7-30	14
`percentile`	integer	1-100 (outside the range → `400 ER0307`)	-

Important limitations:

Maximum date range for trends: 30 days. If no dates specified, defaults to last 30 days.
Maximum 5 fields per request.

Trends example request

http

GET /v1/news/trends?field=entity.id&compare=true&compare_window=7DAYS&trending=true&per_page=5

Trends example response

json

{
    "status": "ok",
    "field": "entity.id",
    "per_page": 5,
    "offset": 0,
    "total_count": 15420,
    "total_articles": 125000,
    "sort": "count",
    "order": "desc",
    "mincount": 1,
    "compare_window": "7DAYS",
    "trending_days": 14,
    "trends": [
        {
            "value": {
                "id": 1034399,
                "name": "Germany",
                "type_id": 2,
                "wikidata_id": "Q183"
            },
            "count": 2341,
            "percentage": 1.87,
            "growth_rate": 4.2,
            "previous_count": 1890,
            "change_absolute": 451,
            "change_percent": 23.86,
            "trending_score": 1.45,
            "trending_history": {
                "2024-01-01": 120,
                "2024-01-02": 145,
                "2024-01-03": 180,
                "2024-01-04": 210,
                "2024-01-05": 195
            }
        }
    ],
    "request_id": "b2c3d4e5-f6g7-8h9i-0j1k-l2m3n4o5p6q7"
}

Reference endpoints response structure

Added in 1.0.42

Applies to the People, Companies and Journalists endpoints.

List endpoints (/v1/people, /v1/companies, /v1/journalists) return a page of profiles. Profile endpoints (/v1/{resource}/{id}) return one profile with coverage and recent_articles.

List response format

Field	Type	Description
`status`	string	`ok` on success.
`limit`	integer	Results per page.
`page`	integer	Current page number.
`has_next_pages`	boolean	Whether more pages are available.
`results`	array	Array of profile objects (see below).

Person / Company object

json

{
  "id": 1316868,
  "name": "Michelle Obama",
  "type": "person",
  "links": {
    "self": "https://api.apitube.io/v1/people/1316868",
    "articles": "https://api.apitube.io/v1/news/entity/1316868",
    "wikipedia": "https://en.wikipedia.org/wiki/Michelle_Obama",
    "wikidata": "https://www.wikidata.org/wiki/Q13133"
  },
  "profile": { "title": "attorney at law", "gender": "female", "nationality": "United States" },
  "coverage": { "...": "see Coverage object" },
  "recent_articles": [ "... Article objects ..." ]
}

Field	Type	Description
`id`	integer	Entity ID (use with `/v1/people/{id}` or `/v1/companies/{id}`).
`name`	string	Display name.
`type`	string	Entity type (`person`, `organization`, `brand`, …).
`links`	object	`self`, `articles`, `wikipedia`, `wikidata`.
`profile`	object	Background details. People: `title`, `bio_summary`, `gender`, `nationality`, `date_of_birth`, `social_profiles`, `aliases`. Companies: `headquarters`, `founded`, `website_url`, `logo_url`, `key_people`, `subsidiaries`.
`coverage`	object	Coverage block (profile responses only). See Coverage object.
`recent_articles`	array	Latest articles mentioning the entity (Article object).

Journalist object

Field	Type	Description
`id`	integer	Journalist (author) ID.
`name`	string	Journalist name.
`outlets`	array	Publishers associated with this name: `{ id, name, domain }`. Bylines with the same name are grouped together.
`outlet_count`	integer	Number of outlets (list responses only).
`links`	object	`self`, `articles`.
`coverage`	object	Coverage block (profile responses only); includes `top_entities`.
`recent_articles`	array	The journalist's latest articles.

Coverage object

json

{
  "article_count": 180,
  "first_seen": "2017-01-06",
  "last_seen": "2026-03-03",
  "sentiment": { "positive": 47, "neutral": 95, "negative": 27 },
  "momentum": { "last_30_days": 12, "previous_30_days": 8, "change_pct": 50 },
  "timeline": [ { "period": "2026-02-01", "count": 13 } ],
  "top_sources": [ { "id": 342, "name": "cbc.ca", "domain": "cbc.ca", "count": 9 } ],
  "top_topics": [ { "id": "politics", "name": "Politics", "count": 70 } ],
  "top_countries": [ { "id": 102, "name": "United States", "code": "us", "count": 55 } ],
  "top_languages": [ { "id": 1, "name": "English", "code": "en", "count": 118 } ],
  "related_entities": [ { "id": 1316867, "name": "Barack Obama", "count": 348 } ]
}

Field	Type	Description
`article_count`	integer	Total matching articles.
`first_seen`	string	Date of the earliest matching article (`YYYY-MM-DD`), or `null`.
`last_seen`	string	Date of the latest matching article (`YYYY-MM-DD`), or `null`.
`sentiment`	object	Article counts by overall tone: `positive`, `neutral`, `negative`.
`momentum`	object	`last_30_days`, `previous_30_days`, and `change_pct` (percentage change, `null` if no prior data).
`timeline`	array	Monthly counts (chronological, up to 24 months): `{ "period": "YYYY-MM-01", "count" }`.
`top_sources`	array	Top sources by article count (people/companies/sources): `{ id, name, domain, count }`.
`top_topics`	array	Topics most often found in matching articles: `{ id, name, count }`.
`top_countries`	array	Countries represented in the coverage: `{ id, name, code, count }`.
`top_languages`	array	Languages used in matching articles: `{ id, name, code, count }`.
`related_entities`	array	People, companies or other entities most often mentioned together with this subject: `{ id, name, count }`.
`top_entities`	array	Entities the journalist covers most (journalists only): `{ id, name, count }`.

API response example

json

{
  "status": "ok",
  "limit": 2,
  "path": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1",
  "page": 1,
  "has_next_pages": true,
  "next_page": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=2",
  "has_previous_page": false,
  "previous_page": "",
  "export": {
    "json": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=json",
    "xlsx": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xlsx",
    "csv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=csv",
    "tsv": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=tsv",
    "xml": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=xml",
    "rss": "https://api.apitube.io/v1/news/everything?language.code=en&per_page=2&page=1&export=rss"
  },
  "request_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "results": [
    {
      "id": 12345678,
      "href": "https://example.com/tech/new-smartphone-release",
      "published_at": "2023-06-15T10:30:00Z",
      "title": "New XYZ Smartphone Makes Waves in the Market",
      "description": "XYZ Company has introduced a new flagship smartphone that significantly outperforms competitors in performance and camera quality.",
      "body": "Today, XYZ Company introduced its new flagship smartphone. The device is equipped with the latest generation processor and a revolutionary camera that, according to the manufacturer, is capable of taking professional quality photos even in low light conditions. Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
      "body_html": "<p>Today, XYZ Company introduced its new flagship smartphone. The device is equipped with the latest generation processor and a revolutionary camera that, according to the manufacturer, is capable of taking professional quality photos even in low light conditions. Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.</p>",
      "language": "en",
      "translations": {
        "en": {
          "title": null,
          "description": null
        }
      },
      "author": {
        "id": 5678,
        "name": "John Smith"
      },
      "image": "https://example.com/images/xyz-smartphone.jpg",
      "categories": [
        {
          "id": 199,
          "name": "economy, business and finance",
          "score": 0.6,
          "taxonomy": "iptc_mediatopics",
          "links": {
            "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:04000000"
          }
        }
      ],
      "topics": [
        {
          "id": "industry.financial_news",
          "name": "Finance Industry News",
          "score": 0.1,
          "links": {
            "self": "https://api.apitube.io/v1/news/topic/industry.financial_news"
          }
        }
      ],
      "industries": [
        {
          "id": 456,
          "name": "Consumer Electronics",
          "links": {
            "self": "https://api.apitube.io/v1/news/industry/456"
          }
        }
      ],
      "entities": [
        {
          "id": 789,
          "name": "XYZ Company",
          "type": "organization",
          "links": {
            "self": "https://api.apitube.io/v1/news/entity/789",
            "wikipedia": "https://en.wikipedia.org/wiki/XYZ_Company",
            "wikidata": "https://www.wikidata.org/wiki/Q12345"
          },
          "frequency": 3,
          "title": {
            "pos": [
              {
                "start": 4,
                "end": 15
              }
            ]
          },
          "body": {
            "pos": [
              {
                "start": 6,
                "end": 17
              },
              {
                "start": 122,
                "end": 133
              }
            ]
          },
          "metadata": {
            "name": "XYZ Company",
            "type": "business",
            "country": {
              "code": "US",
              "name": "United States"
            },
            "description": "Technology company"
          }
        }
      ],
      "source": {
        "id": 123,
        "domain": "example.com",
        "home_page_url": "https://example.com",
        "type": "news",
        "bias": "center",
        "rankings": {
          "opr": 8
        },
        "location": {
          "country_name": "United States",
          "country_code": "us"
        },
        "favicon": "https://example.com/favicon.ico"
      },
      "sentiment": {
        "overall": {
          "score": 0.45,
          "polarity": "positive"
        },
        "title": {
          "score": 0.3,
          "polarity": "positive"
        },
        "body": {
          "score": 0.6,
          "polarity": "positive"
        }
      },
      "summary": [
        {
          "sentence": "Today, XYZ Company introduced its new flagship smartphone.",
          "sentiment": {
            "score": 0.2,
            "polarity": "positive"
          }
        },
        {
          "sentence": "Industry experts have already highly rated the novelty, noting its excellent performance and innovative features.",
          "sentiment": {
            "score": 0.8,
            "polarity": "positive"
          }
        }
      ],
      "keywords": ["smartphone", "XYZ", "technology"],
      "links": [
        {
          "url": "https://example.com/related/xyz-previous-model",
          "type": "link"
        }
      ],
      "media": [
        {
          "url": "https://example.com/images/xyz-smartphone.jpg",
          "type": "image"
        },
        {
          "url": "https://example.com/videos/xyz-smartphone-preview.mp4",
          "type": "video"
        }
      ],
      "locations_mentioned": [
        {
          "name": "San Francisco",
          "country": "US",
          "lat": 37.7749,
          "lng": -122.4194,
          "type": "city"
        }
      ],
      "readability": {
        "flesch_kincaid_grade": 9.2,
        "flesch_reading_ease": 58.4,
        "automated_readability_index": 10.1,
        "difficulty_level": "intermediate",
        "target_audience": "general",
        "reading_age": 14,
        "avg_words_per_sentence": 18.3,
        "avg_syllables_per_word": 1.5
      },
      "story": {
        "id": 3019419820,
        "uri": "https://api.apitube.io/v1/news/story/3019419820"
      },
      "shares": {
        "total": 288,
        "facebook": 149,
        "twitter": 74,
        "reddit": 65
      },
      "is_duplicate": false,
      "is_free": true,
      "is_breaking": false,
      "read_time": 2,
      "sentences_count": 3,
      "paragraphs_count": 1,
      "words_count": 60,
      "characters_count": 354
    }
  ]
}

Notes

Missing fields: A field may be absent if the article has no value for it or your plan does not include it.
Date format: All dates in the API are returned in ISO 8601 format (e.g., "2023-06-15T10:30:00Z").
Content limitations: Depending on the subscription plan, the body and body_html fields may contain the full text of the article or only a part of it.
Language and country: The language field and the source.location.country_code field use standard ISO codes (ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries).
Sentiment: The score value ranges from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment.
Translations: translations.en.title and translations.en.description contain English translations. The original fields stay unchanged, and the article body is not translated. Every response includes the block without an extra parameter. For English articles, its fields are null. Translated fields are full on every plan, including Free; only body and body_html are shortened on Free.
Entity metadata: metadata contains extra details about the entity. Available fields depend on its type, such as location, organization or brand.

API Response Structure ​

General response structure ​

Main response fields ​

The meta object ​

meta.prompt ​

meta.warnings ​

Article object fields ​

Article field reference ​

Nested objects ​

Category object ​

Topic object ​

Industry object ​

Entity object ​

Source object ​

Author object ​

Sentiment object ​

Summary object ​

Story object ​

Shares object ​

Links object ​

Media object ​

Error response ​

Error codes ​

Pagination ​

Trends endpoint response structure ​

Single field response ​

Multiple fields response ​

Trends response fields ​

Trend object structure ​

Trend object with time_bucket ​

Value details by field ​

Trends request parameters ​

Trends example request ​

Trends example response ​

Reference endpoints response structure ​

List response format ​

Person / Company object ​

Journalist object ​

Coverage object ​

API response example ​

Notes ​

API Response Structure

General response structure

Main response fields

The meta object

meta.prompt

meta.warnings

Article object fields

Article field reference

Nested objects

Category object

Topic object

Industry object

Entity object

Source object

Author object

Sentiment object

Summary object

Story object

Shares object

Links object

Media object

Error response

Error codes

Pagination

Trends endpoint response structure

Single field response

Multiple fields response

Trends response fields

Trend object structure

Trend object with time_bucket

Value details by field

Trends request parameters

Trends example request

Trends example response

Reference endpoints response structure

List response format

Person / Company object

Journalist object

Coverage object

API response example

Notes