---
url: 'https://docs.apitube.io/platform/news-api/response-structure.md'
description: 'Fields, nested objects and example responses from the APITube News API'
---

# 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](#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`](/platform/news-api/filters#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](/platform/news-api/ai/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](/platform/news-api/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 {#detailed-description-of-article-fields}

| 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 {#detailed-description-of-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 {#enriched-value-formats-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

::: tip Added in 1.0.42
Applies to the [People](/platform/news-api/reference/people), [Companies](/platform/news-api/reference/companies) and [Journalists](/platform/news-api/reference/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 {#list-response-envelope}

| 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](#article-object-fields)).                 |

### 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

1. **Missing fields:** A field may be absent if the article has no value for it or your plan does not include it.

2. **Date format**: All dates in the API are returned in ISO 8601 format (e.g., "2023-06-15T10:30:00Z").

3. **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.

4. **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).

5. **Sentiment**: The `score` value ranges from -1 to 1, where negative values correspond to negative sentiment, and positive values to positive sentiment.

6. **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.

7. **Entity metadata**: `metadata` contains extra details about the entity. Available fields depend on its type, such as location, organization or brand.