# Meltwater Developer Portal

> News & social intelligence for your solution.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Explore+ Analytics Options


This page details the dimensions and measures you can use in your Explore+ analysis queries.

*To learn more about requesting analytics see the [Analyzing Mentions guide](/guides/explore-plus/analyzing-mentions).*

Please note that output for News documents is subject to copyright restrictions.

## Dimensions

| Dimension | Description | Example Values | Sources |
|-----------|-------------|----------------|---------|
| `author_age` | Approximate age group of the document's author | `13-17`, `18-24` | <SourceChips>x, tiktok</SourceChips> |
| `author_gender` | Gender of the document's author | `female`, `male` | <SourceChips>news, x, douyin, weibo, reddit, little_red_book, forums, wechat, pinterest, blogs, bilibili, linevoom, comments, facebook, youku, twitch, kakaotalk, tiktok</SourceChips> |
| `author_handle` | Handle of the document's author | `@john_smith` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, wechat, pinterest, bilibili, linevoom, comments, facebook, youku, twitch, kakaotalk, tiktok</SourceChips> |
| `author_name` | Name of the document's author | `John Smith` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, wechat, pinterest, bilibili, linevoom, comments, facebook, youku, twitch, kakaotalk, tiktok</SourceChips> |
| `author_occupation` | Occupation of the document's author | `engineer`, `economist` | <SourceChips>x</SourceChips> |
| `custom_field` | Custom fields you have created for data structuring, such as brands or topics | `Green energy`, `My brand` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, broadcast</SourceChips> |
| `emoji` | Emoji symbols used in content | `🤣`, `🔥` | <SourceChips>x, douyin, sina weibo, reddit, little_red_book, news, forums, wechat, pinterest, blogs, bilibili, linevoom, comments, instagram, facebook, twitch, kakaotalk, tiktok</SourceChips> |
| `emotion` | Emotion detected within the content | `Joy`, `Anger` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook</SourceChips> |
| `entity_name` | The names of entities detected in the content | `Emerging Technologies`, `Microsoft` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, tender, broadcast</SourceChips> |
| `hashtag` | Hashtags that appear in the document's content | `ai`, `football` | <SourceChips>x, douyin, weibo, reddit, little_red_book, pinterest, bilibili, linevoom, instagram</SourceChips> |
| `image_age` | The approximate ages of people detected in images | `Young Adults`, `Seniors` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `image_emotion` | Emotions shown by people detected in images | `Joy`, `Anger` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `image_gender` | Genders of people detected in images | `Male`, `Female` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `image_object` | Objects recognized within images shared in content | `Handbag`, `Footwear` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `image_people_density` | Sizes of groups of people detected in images | `Crowd`, `Group` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `image_scene` | Scenes detected in images | `race`, `stadium` | <SourceChips>x, douyin, reddit, little_red_book, news, wechat, pinterest, linevoom, twitch</SourceChips> |
| `keyphrase` | Keyphrases found within the document content | `artificial intelligence`, `tesla` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, broadcast</SourceChips> |
| `language` | Language detected for the document | `English`, `French` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, tiktok, broadcast</SourceChips> |
| `location_city` | City where the document was published | `Berlin` | <SourceChips>x, reddit, news, reviews, facebook</SourceChips> |
| `location_country` | Country where the document was published | `United Kingdom`, `South Korea` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, tiktok, broadcast</SourceChips> |
| `location_state` | State where the document was published | `California` | <SourceChips>x, little_red_book, news, forums, reviews, facebook</SourceChips> |
| `mention` | Social media handles mentioned in the document | `adidas`, `rolex` | <SourceChips>x, instagram</SourceChips> |
| `search` | Searches that are matched by the document | `Brand A search`, `Brand B search` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, broadcast</SourceChips> |
| `sentiment` | Sentiment of the document or mention | `positive`, `negative`, `neutral`, `unknown` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, tiktok, broadcast</SourceChips> |
| `source` | Source of the document - called 'Source Type' in the Meltwater application | `News`, `Reddit`, `Facebook` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, tiktok, broadcast</SourceChips> |
| `topic` | Topics detected in content | `shopping`, `arts_and_entertainment/movies` | <SourceChips>x, douyin, weibo, reddit, little_red_book, news, forums, wechat, pinterest, reviews, blogs, bilibili, linevoom, comments, instagram, facebook, youku, twitch, kakaotalk, tiktok, broadcast</SourceChips> |

## Measures

| Measure | Description | Example Values | Sources |
|---------|-------------|----------------|---------|
| `engagement` | Total engagement for articles and posts across news and social, such as social echo for news, and shares and reports of social | `2459` | <SourceChips>news, x, reddit, facebook, instagram, forums, blogs, comments, pinterest, bilibili, wechat, douyin, little_red_book, weibo, linevoom, tiktok, broadcast</SourceChips> |
| `estimated_views` | Approximate number of times an average article from a publication has been viewed | `2459` | <SourceChips>news, x, facebook, instagram, forums, pinterest, bilibili, wechat, youku, twitch, tiktok, broadcast</SourceChips> |
| `reach` | Reach for the document, for example number of followers for social authors, or estimate of number of visitors for a news site | `2459` | <SourceChips>news, rss, x, facebook, reddit, twitch, pinterest, weibo, kakaotalk, tiktok, broadcast</SourceChips> |
| `social_echo` | Number of times an article has been shared on social networks | `2459` | <SourceChips>news, broadcast</SourceChips> |

---

## Listening Analytics Options


The API supports a number of [pre-defined](#predefined) analysis options, plus the ability to specify a custom analysis using the supported [dimensions and measures](#custom) listed below.

*To learn more about requesting analytics see the [Analyzing Earned Media guide](/guides/listening/analyzing-mentions).*

Please note that:

* For **X** use `twitter` as the source name in analytics requests.
* Output for News documents is subject to copyright restrictions.

## Pre-defined analytics {#predefined}

This table summarizes the pre-defined analytics supported by the Meltwater API.

| Analysis Type | Description | Endpoint | Sources |
|---------------|-------------|----------|---------|
| Total volume | Overall number of mentions for the search, plus average per day and per hour | `/v3/analytics/{searchId}` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Daily/hourly volume | Daily and hourly breakdown of mentions volume | `/v3/analytics/{searchId}` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top countries | Most frequent countries for authors of mentions / content | `/v3/analytics/{searchId}` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, broadcast</SourceChips> |
| Top languages | Most frequent languages for mentions / content | `/v3/analytics/{searchId}` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Sentiment | Discrete sentiment breakdown of mentions / content | `/v3/analytics/{searchId}` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top shared links | The links shared most in content that matches your search | `/v3/analytics/{searchId}/top_shared_links` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top keyphrases | Most frequent key phrases that appear in the mentions / content | `/v3/analytics/{searchId}/top_keyphrases` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top topics | Most frequent topics that appear in the mentions / content | `/v3/analytics/{searchId}/top_topics` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top locations | Most frequent locations (country, state, city) of authors in the analyzed content | `/v3/analytics/{searchId}/top_locations` | <SourceChips>news, x, blogs, forums, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, broadcast</SourceChips> |
| Top entities | Most frequent entities that appear in the analyzed content | `/v3/analytics/{searchId}/top_entities` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok, broadcast</SourceChips> |
| Top tags | Most frequent hashtags that appear in the analyzed content | `/v3/analytics/{searchId}/top_tags` | <SourceChips>x, facebook, instagram, tiktok</SourceChips> |
| Top mentions | Most frequent social handles that appear in the analyzed content | `/v3/analytics/{searchId}/top_mentions` | <SourceChips>x, facebook, instagram, tiktok, broadcast</SourceChips> |
| Top shared | The most 'shared' content matching the search | `/v3/analytics/{searchId}/top_shared` | <SourceChips>x</SourceChips> |
| Top sources | Top (most frequent) authors of the content | `/v3/analytics/{searchId}/top_sources` | <SourceChips>x</SourceChips> |

## Custom analytics {#custom}

### Dimensions

| Dimension | Description | Example Values | Sources |
|-----------|-------------|----------------|---------|
| `author_handle` | Handle of the document's author | `@john_smith` | <SourceChips>facebook, reddit, blogs, comments, twitch, pinterest, bilibili, douyin, weibo, wechat, youku, linevoom, kakaotalk, tiktok</SourceChips> |
| `author_name` | Name of the document's author | `John Smith` | <SourceChips>news, rss, blogs, comments, forums, facebook, reddit, twitch, pinterest, bilibili, douyin, weibo, wechat, youku, linevoom, kakaotalk</SourceChips> |
| `discussion_type` | The type of document relating to discussion | `Reply`, `Original Post`, `Repost`, `Quote and Comments` | <SourceChips>youku, wechat, x, sina_weibo, reddit, little_red_book, linevoom, kakaotalk, instagram, forums, comments, bilibili, tiktok</SourceChips> |
| `editorial_source_name` | For news sources only - the name of the source | `Washington Post` | <SourceChips>news, rss</SourceChips> |
| `emotion` | Detected emotion in the document | `Happy`, `Disgust`, `Love` | <SourceChips>wechat, x, sina_weibo, reviews, reddit, pinterest, news, little_red_book, linevoom, kakaotalk, instagram, forums, comments, douyin, bilibili, tiktok, broadcast</SourceChips> |
| `entity_name` | The names of entities detected in the content | `Emerging Technologies`, `Microsoft`, `Joe Biden` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `entity_type` | The types of entities detected in the content | `organization`, `person` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `event_type` | The types of event related to a company detected in the content | `Civil Law`, `Executive Appointment` | <SourceChips>news</SourceChips> |
| `hashtag` | Hashtags that appear in the document's content | `ai`, `football` | <SourceChips>instagram, blogs, youtube, twitch, pinterest, bilibili, douyin, little_red_book, weibo, linevoom, tiktok</SourceChips> |
| `keyphrase` | Keyphrases found within the document content | `artificial intelligence`, `tesla` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `language` | Language detected for the document | `English`, `French`, `German` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `location_city` | City where the document was published | `Berlin` | <SourceChips>news, x, facebook, weibo, broadcast</SourceChips> |
| `location_country` | Country where the document was published | `United Kingdom`, `South Korea` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, broadcast</SourceChips> |
| `location_state` | State where the document was published | `California` | <SourceChips>news, x, facebook, douyin, weibo, broadcast</SourceChips> |
| `media_type` | The media type of the document | `News Article`, `Reddit Post/Comment` | <SourceChips>facebook, rss, youku, wechat, twitch, x, sina_weibo, reviews, reddit, pinterest, news, little_red_book, linevoom, kakaotalk, instagram, forums, comments, blogs, bilibili, douyin, tiktok, broadcast</SourceChips> |
| `mention` | Social media handles mentioned in the document | `meltwater` | <SourceChips>instagram, x, tiktok</SourceChips> |
| `sentiment` | Sentiment of the document or mention | `positive`, `negative`, `neutral`, `unknown` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `shared_link` | Links shared within articles and posts | `http://www.newsite.com/link/to/article` | <SourceChips>news, x, facebook, instagram, reddit, blogs, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, tiktok</SourceChips> |
| `social_source_name` | For social sources only - the name of the source | `Reddit`, `X` | <SourceChips>blogs, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok</SourceChips> |
| `source` | Source of the document - called 'Source Type' in Explore | `News`, `Reddit`, `Facebook` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `source_name` | The name of the source of the document | `Washington Post`, `Reddit`, `Facebook` | <SourceChips>news, rss, x, facebook, instagram, reddit, forums, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `source_url` | The url of the source of the document | `https://nytimes.com` | <SourceChips>news, rss, comments, reviews, forums, x, facebook, instagram, reddit, twitch, pinterest, douyin, wechat, little_red_book, bilibili, youku, kakaotalk, linevoom, tiktok, broadcast</SourceChips> |
| `verified_type` | The verification type of the document author | `Individual`, `Government`, `None` | <SourceChips>x, sina_weibo</SourceChips> |

### Measures

| Measure | Description | Example Values | Sources |
|---------|-------------|----------------|---------|
| `engagement` | Total engagement for articles and posts across news and social, such as social echo for news, and shares and reports of social | `2459` | <SourceChips>news, x, facebook, instagram, forums, blogs, comments, pinterest, bilibili, douyin, little_red_book, weibo, linevoom, tiktok</SourceChips> |
| `estimated_views` | Number of estimated views of the news article, based on the reach of the source | `3965` | <SourceChips>news</SourceChips> |
| `reach` | Reach for the document, for example number of followers for social authors, or estimate of number of visitors for a news site | `1259` | <SourceChips>news, rss, x, facebook, reddit, twitch, pinterest, weibo, kakaotalk, tiktok, broadcast</SourceChips> |
| `social_echo` | Number of times an article has been shared on social networks | `12.68` | <SourceChips>news</SourceChips> |
| `social_echo_facebook` | Number of times an article has been shared on Facebook | `72.7` | <SourceChips>news</SourceChips> |
| `social_echo_reddit` | Number of times an article has been shared on Reddit | `2.09` | <SourceChips>news</SourceChips> |
| `social_echo_x` | Number of times an article has been shared on X | `17.04` | <SourceChips>news</SourceChips> |
| `social_engagement_likes` | Number of likes on a social post | `8457` | <SourceChips>blogs, x, facebook, tiktok</SourceChips> |
| `social_engagement_reactions` | Number of reactions on a social post | `9599` | <SourceChips>blogs, x, facebook, instagram, reddit, douyin, little_red_book, bilibili, kakaotalk, linevoom, tiktok</SourceChips> |
| `social_engagement_replies` | Number of replies on a social post | `2233` | <SourceChips>blogs, x, facebook, tiktok</SourceChips> |
| `social_engagement_shares` | Number of shares on a social post | `50442` | <SourceChips>facebook, pinterest, kakaotalk, linevoom, tiktok</SourceChips> |
| `views` | Number of views of the social post | `10045` | <SourceChips>x, twitch, bilibili, youku, tiktok</SourceChips> |

---

## Analytics Options


Analytics options describe the dimensions and metrics you can request when calling the Meltwater analytics endpoints. The options available depend on the provider you are analysing — Listening, Explore+, or owned social. This section provides a reference for each.

## Available analytics

| Product | Provider | Supported by |
|---|---|---|
| [Listening](/api-reference/analytics-options/listening) | `earned_media` | Listening API analytics |
| [Explore+](/api-reference/analytics-options/explore-plus) | `explore_plus` | Explore+ API analytics |
| [Owned Social](/api-reference/analytics-options/owned-social) | `owned_social` | Social Analytics — owned posts |

## Conventions used across all analytics

* Output for News documents is subject to copyright restrictions.
* For owned social analytics requests, use `twitter` as the source name for **X** data.

---

## Owned Social Analytics Options


The tables below summarise the metrics and dimensions available for owned social analytics, organised by social network. Learn more about owned social analytics features by reading our [developer documentation](/guides/social-analytics/overview).

Please note that for **X** use `twitter` as the source name in API requests.

---

## Facebook

### Account metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Page fans** | `page_fans` | int | The total number of people who have liked your page. |
| **Page fan adds** | `page_fan_adds` | int | The number of new people who have liked your page. |
| **Page fan removes** | `page_fan_removes` | int | The number of people who have unliked your page. |
| **Page post engagements** | `page_post_engagements` | int | The number of times people have engaged with your posts through reactions, comments, shares, etc. |
| **Page impressions** | `page_impressions` | int | The number of times any content from your page (or about your page) entered a person's screen. |
| **Page organic impressions (unique users)** | `page_impressions_organic_unique` | int | The number of people who had any content from your Page or about your Page enter their screen through unpaid distribution. |
| **Page organic impressions** | `page_impressions_organic` | int | The number of times any post or story content from your page (or about your page) entered a person's screen through unpaid distribution. |
| **Page impressions (unique users)** | `page_impressions_unique` | int | The number of people who had any content from your Page or about your Page enter their screen. |
| **Page impressions viral** | `page_impressions_viral` | int | The number of times any content from your Page or about your Page entered a person's screen with social information attached. |
| **Page impressions viral (unique users)** | `page_impressions_viral_unique` | int | The number of people who had any content from your Page or about your Page enter their screen with social information attached. |
| **Page video views** | `page_video_views` | int | The number of times your page's videos played for at least 3 seconds. |
| **Page video view time** | `page_video_view_time` | int | The total time, in milliseconds, people viewed your page's video. |
| **Page fans gender and age** | `demographics_gender_age` | nested-breakdown | An estimated breakdown by gender and age of the people who have liked your page. |
| **Page fans countries** | `demographics_audience_country` | breakdown | A breakdown by country of the people who have liked your page. |
| **Page fans cities** | `demographics_audience_city` | breakdown | A breakdown by city of the people who have liked your page. |

### Post metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Post reactions** | `reactions_count` | int | Total reactions for the post. |
| **Post clicks links** | `post_clicks_link` | int | Total number of clicks on links in the post. |
| **Post clicks other** | `post_clicks_other` | int | Total number of clicks on other content in the post. |
| **Post clicks photo** | `post_clicks_photo` | int | Total number of clicks on photos in the post. |
| **Post clicks video** | `post_clicks_video` | int | Total number of clicks on videos in the post. |
| **Post like reactions** | `post_reactions_like_total` | int | Total "like" reactions for the post. |
| **Post love reactions** | `post_reactions_love_total` | int | Total "love" reactions for the post. |
| **Post wow reactions** | `post_reactions_wow_total` | int | Total "wow" reactions for the post. |
| **Post haha reactions** | `post_reactions_haha_total` | int | Total "haha" reactions for the post. |
| **Post sorry reactions** | `post_reactions_sorry_total` | int | Total "sorry" reactions for the post. |
| **Post anger reactions** | `post_reactions_anger_total` | int | Total "anger" reactions for the post. |
| **Post comments** | `comments_count` | int | Total number of comments for the post. |
| **Post shares** | `shares_count` | int | Total number of shares for the post. |
| **Post engagement** | `engagements` | float | Shares + comments + reactions + click counts. |
| **Post engagement rate** | `engagement_rate` | float | The number of users who engaged with the post divided by the number that saw the post. |
| **Post impressions** | `post_impressions` | int | The number of times the post entered a person's screen. |
| **Post organic impressions** | `post_impressions_organic` | int | The number of times the post entered a person's screen through unpaid distribution. |
| **Post engagement rate from page fans** | `page_fans_engagement_rate` | float | The number of page fans who engaged with the post divided by the number that saw the post. |
| **Post clicks** | `post_clicks` | int | The number of times people clicked anywhere in the post without generating a story. |
| **Post clicks (unique users)** | `post_clicks_unique` | int | The number of people who clicked anywhere in the post without generating a story. |
| **Post engaged users** | `post_engaged_users` | int | The number of people who clicked anywhere in the post. |
| **Post organic impressions (unique users)** | `post_impressions_organic_unique` | int | The number of people who had the post enter their screen through unpaid distribution. |
| **Post impressions (unique users)** | `post_impressions_unique` | int | The number of people who had the post enter their screen. |
| **Post video average time watched** | `post_video_avg_time_watched` | int | The average time (in milliseconds) for which people viewed the post's video. |
| **Post video total view time** | `post_video_view_time` | int | The total time (in milliseconds) the post's video has been played for, including videos played for less than 3 seconds and replays. Returns 0 for reshared videos. |
| **Post video views** | `post_video_views` | int | The number of times the post's video has been played for at least 3 seconds. |
| **Post organic video views** | `post_video_views_organic` | int | The number of times the post's video, through unpaid distribution, has been played for at least 3 seconds. |

---

## Instagram

### Account metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Email contacts** | `email_contacts` | int | Total number of taps on the email link in the IG User's profile. |
| **Followers** | `total_followers_count` | int | Total number of followers. |
| **New followers** | `follower_count` | int | Number of new followers each day within the specified range. |
| **Get directions clicks** | `get_directions_clicks` | int | Total number of taps on the directions link in the IG User's profile. |
| **Phone call clicks** | `phone_call_clicks` | int | Total number of taps on the call link in the IG User's profile. |
| **Text message clicks** | `text_message_clicks` | int | Total number of taps on the text message link in the IG User's profile. |
| **Website clicks** | `website_clicks` | int | Total number of clicks on the website link in the Instagram user's profile. |
| **Profile views** | `profile_views` | int | Total number of users who have viewed the Instagram user's profile. |
| **Total impressions** | `impressions` | int | Total number of times the Instagram user's media have been viewed. |
| **Followers gender and age** | `demographics_gender_age` | nested-breakdown | An estimated breakdown by gender and age of followers of the account. |
| **Followers countries** | `demographics_audience_country` | breakdown | A breakdown by country of the followers of the account. |
| **Followers cities** | `demographics_audience_city` | breakdown | A breakdown by city of the followers of the account. |

### Post metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Post comments** | `comments_count` | int | Total number of comments for the post. |
| **Post engagement** | `engagement` | int | Sum of likes, comment, shares, and saved counts on the IG Media. |
| **Post engagement rate** | `engagement_rate` | float | The number of users who engaged with the post divided by the number that saw the post. |
| **Post exits** | `exits` | int | Total number of times someone exited the story IG Media object. |
| **Post impressions** | `impressions` | int | Total number of times the post has been seen. |
| **Post likes** | `like_count` | int | Total "like" reactions for the post. |
| **Post plays** | `plays` | int | Number of times the reels starts to play after an impression is already counted. |
| **Post reach** | `reach` | int | Total number of unique Instagram accounts that have seen the post. |
| **Post replies** | `replies` | int | Total number of replies. |
| **Post saves** | `saved` | int | Total number of unique Instagram accounts that have saved the post. |
| **Post shares** | `shares` | int | Total number of shares. |
| **Post taps back** | `taps_back` | int | Total number of taps to see this story IG Media object's previous photo or video. |
| **Post taps forward** | `taps_forward` | int | Total number of taps to see this story IG Media object's next photo or video. |
| **Post total interactions** | `total_interactions` | int | Number of likes, saves, comments, and shares on the reel, minus the number of unlikes, unsaves, and deleted comments. |
| **Post followers count engagement rate** | `followers_count_engagement_rate` | float | The percentage of followers that engaged with the post. |

---

## LinkedIn

### Account metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Followers** | `followers` | int | Total number of followers. |
| **Organic follower gain** | `organic_follower_gain` | int | Total number of organic followers gained. |
| **Paid follower gain** | `paid_follower_gain` | int | Total number of paid followers gained. |
| **Desktop page views** | `all_desktop_page_views` | int | Total number of desktop page views. |
| **Mobile page views** | `all_mobile_page_views` | int | Total number of mobile page views. |
| **Page views** | `all_page_views` | int | Total number of page views. |

### Post metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Post click count** | `click_count` | int | Total number of clicks for the post. |
| **Post comment count** | `comment_count` | int | Total number of comments for the post. |
| **Post engagement** | `engagements` | float | Total engagement for the post. |
| **Post engagement rate** | `engagement_rate` | float | The number of users who engaged with the post divided by the number that saw the post. |
| **Post impression count** | `impression_count` | int | Total number of impressions for the post. |
| **Post like count** | `like_count` | int | Total number of likes for the post. |
| **Post share count** | `share_count` | int | Total number of shares for the post. |
| **Post video views** | `video_view` | int | Total number of video views for the post. |

---

## TikTok

### Account metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Fans** | `fans` | int | Total number of fans for the account. |
| **Net new fans** | `net_new_fans` | int | Net new fans for the account. |
| **Profile views** | `profile_views` | int | Total number of profile views for the account. |
| **Video views** | `video_views` | int | Total number of video views for the account. |

### Post metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Post average watch time** | `average_watch_time` | float | The average watch time for the video. |
| **Post comments** | `comments` | int | The total number of comments the video has received. |
| **Post engagement rate** | `engagement_rate` | float | Total engagement rate for the video. |
| **Post engagement** | `engagements` | float | Total engagement for the video. |
| **Post full video watched rate** | `full_video_watch_rate` | float | Percentage of viewers who viewed the whole video. |
| **Post likes** | `likes` | int | The total number of likes the video has received. |
| **Post reach** | `reach` | int | Total number of unique viewers who viewed the video. |
| **Post shares** | `shares` | int | The total number of times the video has been shared. |
| **Post video views** | `video_views` | int | The total number of views the video has received. |

---

## X

*Note: Use `twitter` as the source name in API requests for X.*

### Account metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Followers** | `followers_count` | int | Total number of followers. |

### Post metrics

| Name | Metric | Type | Description |
|------|--------|------|-------------|
| **Post app install attempts** | `app_install_attempts` | int | A count of how many times an App Install event has occurred from the post. |
| **Post app opens** | `app_opens` | int | A count of how many times an App Open event has occurred from the post. |
| **Post detail expands** | `detail_expands` | int | A count of how many times the post has been clicked to see more details. |
| **Post email tweet** | `email_tweet` | int | A count of how many times the post has been shared via email. |
| **Post engagement rate** | `engagement_rate` | float | Engagement rate for the post. |
| **Post engagements** | `engagements` | int | A count of the number of times a user has interacted with the post. |
| **Post favorites** | `favorites` | int | A count of how many times the post has been favorited. |
| **Post hashtag clicks** | `hashtag_clicks` | int | A count of how many times a hashtag in the post has been clicked. |
| **Post impressions** | `impressions` | int | A count of how many times the post has been viewed. |
| **Post media clicks** | `media_clicks` | int | A count of how many times media such as an image or video in the post has been clicked. |
| **Post media engagements** | `media_engagements` | int | A count of how many times media such as an image or video in the post has been engaged with. |
| **Post media views** | `media_views` | int | A count of all views (autoplay and click) of your media counted across videos, gifs, and images. |
| **Post permalink clicks** | `permalink_clicks` | int | A count of how many times the permalink to the post has been clicked. |
| **Post quote posts** | `quote_tweets` | int | A count of times a post has been reposted with a comment. |
| **Post replies** | `replies` | int | A count of how many times the post has been replied to. |
| **Post reposts** | `retweets` | int | A count of how many times the post has been reposted. |
| **Post unfavorites** | `unfavorites` | int | A count of how many times a favorite on the post was removed. |
| **Post unquote posts** | `unquote_tweets` | int | A count of how many times a quote of the post was removed. |
| **Post unreplies** | `unreplies` | int | A count of how many times a reply to the post was removed. |
| **Post un-reposts** | `unretweets` | int | A count of how many times a repost of the post was removed. |
| **Post url clicks** | `url_clicks` | int | A count of how many times a URL in the post has been clicked. |
| **Post user follows** | `user_follows` | int | A count of how many times the User (post author) has been followed from this post. |
| **Post user profile clicks** | `user_profile_clicks` | int | A count of how many times the User (post author) has had their profile clicked from this post. |
| **Post user unfollows** | `user_unfollows` | int | A count of how many times the User (post author) has been unfollowed. |
| **Post video starts** | `video_starts` | int | A count of how many times a video in the post started. |
| **Post video views** | `video_views` | int | A count of how many times a video in the given post has been 50% visible for at least two seconds. |
| **Post video viewed 100** | `video_viewed_100` | int | A count of how many times 100% of a video in the post was watched. |
| **Post video viewed 25** | `video_viewed_25` | int | A count of how many times 25% of a video in the post was watched. |
| **Post video viewed 50** | `video_viewed_50` | int | A count of how many times 50% of a video in the post was watched. |
| **Post video viewed 75** | `video_viewed_75` | int | A count of how many times 75% of a video in the post was watched. |
| **Post video viewed 95** | `video_viewed_95` | int | A count of how many times 95% of a video in the post was watched. |

---

## Overview

# API Reference

The Meltwater API is a RESTful API at https://api.meltwater.com that provides programmatic access to Meltwater content, analytics and insights.

:::tip New to the Meltwater API?
Start with the [Getting Started guide](/guides/getting-started/overview) to set up your API credentials and understand usage limits before diving into the reference docs.
:::

We are currently building out a new API version, version 4, which in time will support all features. For now, newer features are supported by v4 and some features remain in v3. We will communicate to API customers planned deprecation dates for features.

## OpenAPI Specification

The full V3 API is described by an OpenAPI specification you can download and use to generate client libraries or import into tools such as Postman or Insomnia:

[Download the V3 OpenAPI spec](pathname:///v3.yaml)

## Authentication

The Meltwater API uses API tokens to authenticate requests.

If you have lost or forgotten your API token, you can revoke your existing token and create a new token as explained on the [API Credentials page](/guides/getting-started/api-credentials).

For API calls, authentication is performed by providing the API token as a header named `apikey` on the request.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

If you are using a connector (such as for a BI tool) you will be asked to enter your API token — use the same token as described on the [API Credentials page](/guides/getting-started/api-credentials).

## Usage Limits

The Meltwater API enforces rate limits and usage quotas depending on your API package. For details on limits and how to monitor your usage, see the [Usage Limits guide](/guides/getting-started/usage-limits).

## Status & Error Codes

Meltwater uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 200 range indicate success. Codes in the 400 range indicate an error that failed given the information provided (for example, a required parameter was omitted). Codes in the 500 range indicate an error with Meltwater's servers.

| Code | Description |
|------|-------------|
| `200 OK` | Your request was successful. |
| `400 Bad request` | There is an issue with your request. Check you are providing all required parameters. |
| `401 Unauthorized` | Check you are providing the correct authentication header and API token. |
| `403 Forbidden` | You are not authorized to access the endpoint. |
| `409 Conflict` | The change you're making conflicts with a resource or query that already exists. |
| `429 Too Many Requests` | You've reached your rate limit. |
| `500 Internal Service Error` | An error occurred on the Meltwater servers. |
| `503 Service Unavailable` | An error occurred on the Meltwater servers. |

For Earned Analytics, a `429` may indicate that the service is currently processing a large number of analytics queries. The API will respond with the message body "Service overloaded, please try again later" when this occurs. Please try your request again after the timestamp found in the attached `Retry-After` header.

## Request IDs

Each API request has an associated request identifier. You can find this value in the response headers under `X-Request-Id`. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

```
X-Request-Id: e708864855f3bb69c4d9a213b9108b9f
```

---

## API JSON

# API JSON (`api.json`)

The recommended general-purpose template for most API integrations. Includes all data fields most customers need.

## At a glance

| | |
|---|---|
| **Template code** | `api.json` |
| **Output formats** | JSON |
| **Supported endpoints** | Listening API exports, Listening API streaming, Explore+ API search |
| **Streaming support** | Yes |

See [Conventions](/api-reference/templates/overview#conventions-used-across-all-templates) for behaviour shared across all templates.

## Field reference

<TemplateFields fields={apiJsonData.fields} format="JSON" />

---

## Popular Fields & Metrics

# Popular Fields & Metrics (`app.standard`)

A curated selection of the most commonly used fields, designed for analysts bringing data into spreadsheets and BI tools.

## At a glance

| | |
|---|---|
| **Template code** | `app.standard` |
| **Output formats** | CSV, XLSX |
| **Supported endpoints** | Listening API exports |
| **Streaming support** | No |

See [Conventions](/api-reference/templates/overview#conventions-used-across-all-templates) for behaviour shared across all templates.

## Field reference

<TemplateFields fields={appStandardData.fields} format="CSV" />

---

## Legacy CSV

# Legacy CSV Template

:::warning Deprecated
This is the CSV output you receive from a Listening API export when no `template` field is specified on the request. For new integrations, use [Popular Fields & Metrics](/api-reference/templates/app-standard) instead.
:::

## At a glance

| | |
|---|---|
| **Template code** | _(default when no `template` is specified)_ |
| **Output format** | CSV |
| **Supported endpoints** | Listening API exports |
| **Streaming support** | No |

## Important notes

* Country is rarely populated for Blogs and Comments.
* Fields without a CSV column are omitted from this template.

See [Conventions](/api-reference/templates/overview#conventions-used-across-all-templates) for behaviour shared across all templates.

## Field reference

<TemplateFields fields={legacyCsvData.fields} format="CSV" categories={legacyCategories} sourcesMode="earned-only" />

---

## Legacy JSON

# Legacy JSON Template

:::warning Deprecated
This is the JSON output you receive from a Listening API export or stream when no `template` field is specified on the request. For new integrations, use [API JSON](/api-reference/templates/api-json) instead.
:::

## At a glance

| | |
|---|---|
| **Template code** | _(default when no `template` is specified)_ |
| **Output format** | JSON |
| **Supported endpoints** | Listening API exports, Listening API streaming |
| **Streaming support** | Yes |

## Important notes

* Country is rarely populated for Blogs and Comments.

See [Conventions](/api-reference/templates/overview#conventions-used-across-all-templates) for behaviour shared across all templates.

## Field reference

<TemplateFields fields={legacyJsonData.fields} format="JSON" categories={legacyCategories} sourcesMode="earned-only" />

---

## Content Output Templates


Output templates control the shape of the data returned by the API for export, search and streaming features. You specify a template by setting the `template` field on your request.

## Available templates

| Template | Code | Formats | Supported by |
|---|---|---|---|
| [API JSON](/api-reference/templates/api-json) | `api.json` | JSON | Listening API exports, Listening API streaming, Explore+ API search |
| [Popular Fields & Metrics](/api-reference/templates/app-standard) | `app.standard` | CSV, XLSX | Listening API exports |
| [Legacy JSON](/api-reference/templates/legacy-json) | _(default when no `template` is specified)_ | JSON | Listening API exports, Listening API streaming |
| [Legacy CSV](/api-reference/templates/legacy-csv) | _(default when no `template` is specified)_ | CSV | Listening API exports |

## Choosing a template

- **Building a JSON integration?** For most cases use [API JSON](/api-reference/templates/api-json). It includes all the fields most customers need and is supported across Listening exports, Listening streaming, and Explore+ search.
- **Pulling data into a spreadsheet or BI tool?** For most cases use [Popular Fields & Metrics](/api-reference/templates/app-standard).
- **Maintaining an older integration?** [Legacy JSON](/api-reference/templates/legacy-json) and [Legacy CSV](/api-reference/templates/legacy-csv) are what you receive if no `template` field is specified, depending on the output format you request. We recommend migrating to [API JSON](/api-reference/templates/api-json) or [Popular Fields & Metrics](/api-reference/templates/app-standard) for new work.

## Conventions used across all templates

* All returned strings are encoded using UTF-16.
* All datetime values are output in ISO-8601 format, in UTC timezone.
* Output for News documents is subject to copyright restrictions.
* Fields marked **Explore+ only** are only applicable to output from the Explore+ API.
* Fields marked **Exports only** are not available in streaming output.

---

## Add tags to documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Add tags to documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/documents/add_tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggers a request to add a list of specified tags to a given set of documents. This is an asynchronous operation.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./add-tags.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./add-tags.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./add-tags.StatusCodes.json")}
>
  
</StatusCodes>

---

## Allows to fetch the top posts for owned social accounts

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Allows to fetch the top posts for owned social accounts"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts/posts/top_posts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Allows to fetch the top posts for owned social accounts. You might do this to report the most engaged with posts in a period of time for example. Timestamps in this endpoint for Facebook and Instagram sources work on PST timezone (Meta's preferred timezone).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./allows-to-fetch-the-top-posts-for-owned-social-accounts.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./allows-to-fetch-the-top-posts-for-owned-social-accounts.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./allows-to-fetch-the-top-posts-for-owned-social-accounts.StatusCodes.json")}
>
  
</StatusCodes>

---

## Analyse earned data in your private index.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Analyse earned data in your private index."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/analytics/custom"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Analyse earned data in your private index.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./analyse-earned-data-in-your-private-index.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./analyse-earned-data-in-your-private-index.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./analyse-earned-data-in-your-private-index.StatusCodes.json")}
>
  
</StatusCodes>

---

## Chat completion endpoint

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Chat completion endpoint"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/mira/chat"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Processes chat completion requests and returns responses in streaming or non-streaming mode.
If thread_id is provided, it will use that thread. If not, it will create a new thread or use the latest one.
If X-Project-ID header is provided, the thread will be associated with that project for enhanced context.
The thread ID is returned in the Thread-ID response header.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./chat-completion-endpoint.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./chat-completion-endpoint.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./chat-completion-endpoint.StatusCodes.json")}
>
  
</StatusCodes>

---

## Chat responses endpoint

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Chat responses endpoint"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/mira/responses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Processes chat responses requests with multiple input messages and returns responses in streaming or non-streaming mode.
If Thread-ID header is provided, uses the existing thread; otherwise creates a new thread with all messages and passes only the last user message to Mira.
The thread ID is returned in the Thread-ID response header.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./chat-responses-endpoint.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./chat-responses-endpoint.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./chat-responses-endpoint.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a custom analytics request

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a custom analytics request"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/analytics/{searchId}/custom"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a custom analytics request with your choice of filters and analytic types and configuration.

Please see example requests/responses below or our guide on Custom Analytics [here](/guides/listening/analyzing-mentions) for more information.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-custom-analytics-request.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-custom-analytics-request.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-custom-analytics-request.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a new assignment rule.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new assignment rule."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}/rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new assignment rule.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-new-assignment-rule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-new-assignment-rule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-new-assignment-rule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a new custom field value.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new custom field value."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new custom field value.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-new-custom-field-value.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-new-custom-field-value.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-new-custom-field-value.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a new custom field.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new custom field."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/assets/custom_fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new custom field.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-new-custom-field.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-new-custom-field.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-new-custom-field.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a new search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new search."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/assets/searches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-new-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-new-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-new-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a new tag

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a new tag"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new tag for tagging documents. Tag names must be unique and a maximum of 128 characters.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-a-new-tag.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-a-new-tag.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-a-new-tag.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search for Meltwater earned data using a saved search and optional filters.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search for Meltwater earned data using a saved search and optional filters."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/search/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Search for Meltwater earned data using a saved search and optional filters.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-earned-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-earned-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-earned-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Creates a hook

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Creates a hook"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/hooks"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a hook for one of your predefined searches.
 Delivers search results for the query referenced by the `search_id` to the `target_url` via HTTP POST. Note that a `hook_id` will be returned on successful creation, this id is needed to delete the hook.

 We are also returning the header: `X-Hook-Secret`, a shared secret used to sign the document body pushed to your `target_url`.

 Specify `company_id` if your `search_id` is not in your default company.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-hook.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-hook.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-hook.StatusCodes.json")}
>
  
</StatusCodes>

---

## Creates a new one-time export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Creates a new one-time export"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/exports/one-time"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-onetime-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-onetime-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-onetime-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Creates a new recurring export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Creates a new recurring export"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/exports/recurring"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-recurring-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-recurring-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-recurring-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create a search

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a search"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/searches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete a given assignment rule.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a given assignment rule."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}/rules/{rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a given assignment rule.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-a-given-assignment-rule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-a-given-assignment-rule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-a-given-assignment-rule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete a given custom field value.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a given custom field value."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a given custom field value.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-a-given-custom-field-value.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-a-given-custom-field-value.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-a-given-custom-field-value.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete a given custom field.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a given custom field."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a given custom field.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-a-given-custom-field.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-a-given-custom-field.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-a-given-custom-field.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete a given search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete a given search."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/explore_plus/assets/searches/{search_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a given search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-a-given-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-a-given-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-a-given-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete an existing tag.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an existing tag."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/tags/{tag_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes a given tag. Any documents that possess this tag will have it removed following tag deletion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-an-existing-tag.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-an-existing-tag.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-an-existing-tag.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete an existing hook.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an existing hook."}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/hooks/{hook_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an existing hook.
 Removes the hook and stops sending any search results to the target_url.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-hook.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-hook.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-hook.StatusCodes.json")}
>
  
</StatusCodes>

---

## Removes an existing one-time export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Removes an existing one-time export"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/exports/one-time/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-onetime-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-onetime-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-onetime-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Removes an existing recurring export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Removes an existing recurring export"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/exports/recurring/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-recurring-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-recurring-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-recurring-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete an individual search

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete an individual search"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/v3/searches/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch a given assignment rule.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch a given assignment rule."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}/rules/{rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch a given assignment rule.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./fetch-a-given-assignment-rule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-a-given-assignment-rule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-a-given-assignment-rule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch a given custom field value.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch a given custom field value."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch a given custom field value.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./fetch-a-given-custom-field-value.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-a-given-custom-field-value.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-a-given-custom-field-value.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch a given custom field.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch a given custom field."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch a given custom field.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./fetch-a-given-custom-field.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-a-given-custom-field.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-a-given-custom-field.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch a given search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch a given search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/searches/{search_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch a given search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./fetch-a-given-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-a-given-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-a-given-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch available analytics options.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch available analytics options."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/analytics/custom/catalog"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch available analytics options.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-available-analytics-options.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-available-analytics-options.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch the latest custom analytics options

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch the latest custom analytics options"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/custom/catalog"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch the latest dimensions, measures, and analytic types you can use to create your custom analytic requests.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./fetch-the-latest-custom-analytics-options.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./fetch-the-latest-custom-analytics-options.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all hooks.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all hooks."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/hooks"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all hooks.

Delivers all previously generated hooks.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-all-hooks.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-all-hooks.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get an individual hook.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an individual hook."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/hooks/{hook_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get an individual hook.

Retrieves an existing hook.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-hook.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-hook.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-hook.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get import batch

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import batch"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/imports/batches/{batch_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves status and statistics about an import batch.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-import-batch.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-import-batch.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-import-batch.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get import tag

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get import tag"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/imports/import_tags/{import_tag}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves status and statistics about an import tag.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-import-tag.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-import-tag.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-import-tag.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get an individual search

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an individual search"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/searches/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get usage information on specific metric

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get usage information on specific metric"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/usage/me/metrics/{metric}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get usage information on specific metric

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-usage-information-on-specific-metric.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-usage-information-on-specific-metric.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-usage-information-on-specific-metric.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get usage statistics for your API calls

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get usage statistics for your API calls"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/usage/me/requests"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get usage statistics for your API calls

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-usage-statistics-for-your-api-calls.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-usage-statistics-for-your-api-calls.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-usage-statistics-for-your-api-calls.StatusCodes.json")}
>
  
</StatusCodes>

---

## A summary of analytics for a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"A summary of analytics for a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The summary is produced only for documents matching the Saved Search,
from the specified document sources, and within the specified time-range.

Any other parameters provided, such as language or country, will further
restrict the documents that are included in the analysis.

The `unique_authors` value can only be calculated for sources other than `news`.
When run against `news` it will return 0.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-search-id-start-end-tz-source-country-language-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-search-id-start-end-tz-source-country-language-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-search-id-start-end-tz-source-country-language-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top named entities that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top named entities that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_entities"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of entities that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top keyphrases produced,
defaulting to the top `100` keyphrases.

The sentiment parameter allows you to select the sentiment of the documents to analyze.

Any other parameters provided, such as language or country, will further
restrict the documents that have their keyphrases included.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-entities-search-id-start-end-tz-source-country-language-size-sentiment-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-entities-search-id-start-end-tz-source-country-language-size-sentiment-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-entities-search-id-start-end-tz-source-country-language-size-sentiment-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top keyphrases that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top keyphrases that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_keyphrases"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of keyphrases that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top keyphrases produced,
defaulting to the top `100` keyphrases.

The sentiment parameter allows you to select the sentiment of the documents to analyze.

Any other parameters provided, such as language or country, will further
restrict the documents that have their keyphrases included.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-keyphrases-search-id-start-end-tz-source-country-language-size-sentiment-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-keyphrases-search-id-start-end-tz-source-country-language-size-sentiment-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-keyphrases-search-id-start-end-tz-source-country-language-size-sentiment-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top locations that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top locations that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_locations"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of locations that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top locations produced,
defaulting to the top `100` locations.

The level parameter allows you to select the level of location you want from country, state or city.

Any other parameters provided, such as language or country, will further
restrict the documents that have their keyphrases included.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-locations-search-id-start-end-tz-source-country-language-size-level-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-locations-search-id-start-end-tz-source-country-language-size-level-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-locations-search-id-start-end-tz-source-country-language-size-level-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top mentions that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top mentions that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_mentions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of mentions that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top tags produced,
defaulting to the top `10` mentions.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-mentions-search-id-start-end-tz-source.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-mentions-search-id-start-end-tz-source.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-mentions-search-id-start-end-tz-source.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top shared links that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top shared links that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_shared_links"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of links that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top shared links  produced,
defaulting to the top `100` links.

Any other parameters provided, such as language or country, will further
restrict the documents that have their links included.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-shared-links-search-id-start-end-tz-source-country-language-size-sentiment-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-shared-links-search-id-start-end-tz-source-country-language-size-sentiment-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-shared-links-search-id-start-end-tz-source-country-language-size-sentiment-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top shared documents that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top shared documents that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_shared"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of documents matching the Saved Search that were
the most shared, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top shared documents
produced, defaulting to the top `10` top shared documents.

Any other parameters provided, such as language or country, will further
restrict the documents that are included.

The `sort_by` parameter controls the ranking of the results. For example,
if `sort_by=retweets`, the results will be the top N documents by retweet
count. Retweet results are based on when the retweet occured, not the
creation date of the original tweet

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-shared-search-id-start-end-tz-source-country-language-size-sort-by-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-shared-search-id-start-end-tz-source-country-language-size-sort-by-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-shared-search-id-start-end-tz-source-country-language-size-sort-by-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top sources that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top sources that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_sources"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of "sources" that provided the documents matching the Saved Search.

For social sources, a "source" will be the author of that document.

The `size` parameter controls the maximum number of sources to produce, defaulting
to the top `10` sources.

Any other parameters provided, such as language or country, will further
restrict the documents whose sources will be produced.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-sources-search-id-start-end-tz-source-country-language-size-min-authority-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-sources-search-id-start-end-tz-source-country-language-size-min-authority-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-sources-search-id-start-end-tz-source-country-language-size-min-authority-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top tags that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top tags that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of tags that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top tags produced,
defaulting to the top `10` tags.

Any other parameters provided, such as language or country, will further
restrict the documents that have their tags included.

The type of tags included, such as Twitter "hashtags", will depend on the
selected sources.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-tags-search-id-start-end-tz-source-country-language-size-company-id.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-tags-search-id-start-end-tz-source-country-language-size-company-id.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-tags-search-id-start-end-tz-source-country-language-size-company-id.StatusCodes.json")}
>
  
</StatusCodes>

---

## The top topics that occur in a Saved Search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"The top topics that occur in a Saved Search."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/analytics/{searchId}/top_topics"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Produces a ranked list of topics and their sub topics that occur in documents matching the
Saved Search, from the specified document sources, and within the
specified time-range.

The `size` parameter controls the number of top topics produced,
defaulting to the top `10` mentions.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-v-3-analytics-top-topics-search-id-start-end-tz-source.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-v-3-analytics-top-topics-search-id-start-end-tz-source.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-v-3-analytics-top-topics-search-id-start-end-tz-source.StatusCodes.json")}
>
  
</StatusCodes>

---

## Ingest BYOC documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Ingest BYOC documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/imports/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Handles the import of documents into the Meltwater Platform.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./handle-byoc-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./handle-byoc-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./handle-byoc-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all custom field folders.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all custom field folders."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/custom_fields/folders"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all custom field folders.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-all-custom-field-folders.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-all-custom-field-folders.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-all-custom-field-folders.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all custom fields.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all custom fields."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/custom_fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all custom fields.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-all-custom-fields.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-all-custom-fields.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-all-custom-fields.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all search folders.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all search folders."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/searches/folders"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all search folders.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-all-search-folders.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-all-search-folders.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-all-search-folders.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all searches.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all searches."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/explore_plus/assets/searches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

List all searches.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-all-searches.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-all-searches.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-all-searches.StatusCodes.json")}
>
  
</StatusCodes>

---

## List available projects

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List available projects"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/mira/projects"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieve all projects available to the authenticated user with pagination support

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-available-projects.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-available-projects.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-available-projects.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your companies

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your companies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/accounts/me/companies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-companies.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-companies.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all search custom categories

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all search custom categories"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/custom_categories"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of all search custom categories

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-custom-categories.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-custom-categories.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-custom-categories.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all search filter sets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all search filter sets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/filter_sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of all search filter sets

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-filter-sets.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-filter-sets.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-filter-sets.StatusCodes.json")}
>
  
</StatusCodes>

---

## List import batches

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List import batches"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/imports/batches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of import batches. Supports filtering by date range (start/end) and batch status. Dates are interpreted in the specified timezone (defaults to UTC).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-import-batches.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-import-batches.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-import-batches.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your one-time exports

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your one-time exports"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/exports/one-time"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-onetime-exports.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-onetime-exports.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your recurring exports

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your recurring exports"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/exports/recurring"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-recurring-exports.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-recurring-exports.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your searches

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your searches"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/searches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-searches.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-searches.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-searches.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your tags

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your tags"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-tags.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-tags.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-tags.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your API tokens

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your API tokens"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/accounts/me/tokens"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-tokens.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-tokens.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get a list of all your workspaces

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get a list of all your workspaces"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/accounts/me/workspaces"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-workspaces.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-workspaces.StatusCodes.json")}
>
  
</StatusCodes>

---

## Remove tags from documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove tags from documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/documents/remove_tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggers a request to remove a list of specified tags from a given set of documents. This is an asynchronous operation.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./remove-tags.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./remove-tags.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./remove-tags.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns a break-down over date and time

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns a break-down over date and time"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts/metrics/heatmap"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A 'heatmap' metric is an analysis that provides a break-down over date and time. For example, the `page_fans_heatmap` metric breaks down the audience for a Facebook page by how active they are each day and hour. All timestamps in this endpoint work on PST timezone (Meta's preferred timezone).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./returns-a-break-down-over-date-and-time.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-a-break-down-over-date-and-time.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-a-break-down-over-date-and-time.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns a double-level breakdown by two categories or concepts

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns a double-level breakdown by two categories or concepts"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts/metrics/nested_breakdown"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A 'nested-breakdown' metric is an analysis that provides a double-level breakdown by two categories or concepts. For example, the `demographics_gender_age` metric breaks down the audience for a Facebook page by firstly gender, then age group. All timestamps in this endpoint work on PST timezone (Meta's preferred timezone).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./returns-a-double-level-breakdown-by-two-categories-or-concepts.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-a-double-level-breakdown-by-two-categories-or-concepts.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-a-double-level-breakdown-by-two-categories-or-concepts.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns a list of social account connections for a given company/user account

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns a list of social account connections for a given company/user account"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of social account connections for a given company/user account

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./returns-a-list-of-social-account-connections-for-a-given-company-user-account.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-a-list-of-social-account-connections-for-a-given-company-user-account.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-a-list-of-social-account-connections-for-a-given-company-user-account.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns a list of supported metrics

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns a list of supported metrics"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/supported_metrics"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a list of supported metrics

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-a-list-of-supported-metrics.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-a-list-of-supported-metrics.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns a single-level breakdown by a category or concept

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns a single-level breakdown by a category or concept"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts/metrics/breakdown"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A 'breakdown' metric is an analysis that provides a single-level breakdown by a category or concept. For example, the `demographics_audience_country` metric breaks down the audience for a Facebook page by country. All timestamps in this endpoint work on PST timezone (Meta's preferred timezone).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./returns-a-single-level-breakdown-by-a-category-or-concept.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-a-single-level-breakdown-by-a-category-or-concept.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-a-single-level-breakdown-by-a-category-or-concept.StatusCodes.json")}
>
  
</StatusCodes>

---

## Returns simple metrics for a social account

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Returns simple metrics for a social account"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/owned/accounts/metrics/numeric"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A numeric metric is the most basic type of metrics you can get for your social media account, like the number of page fans. All timestamps in this endpoint work on PST timezone (Meta's preferred timezone).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./returns-simple-metrics-for-a-social-account.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./returns-simple-metrics-for-a-social-account.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./returns-simple-metrics-for-a-social-account.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get an approximate count of results for the search over a particular period

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get an approximate count of results for the search over a particular period"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/searches/{id}/count"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-count.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-count.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-count.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search for data in your private index.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search for data in your private index."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v3/explore_plus/search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Search for data in your private index.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-for-data-in-your-private-index.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-for-data-in-your-private-index.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-for-data-in-your-private-index.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get details of a one-time export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get details of a one-time export"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/exports/one-time/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./show-onetime-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./show-onetime-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./show-onetime-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get details of a recurring export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get details of a recurring export"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v3/exports/recurring/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./show-recurring-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./show-recurring-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./show-recurring-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update a given assignment rule.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a given assignment rule."}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}/rules/{rule_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a given assignment rule.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-a-given-assignment-rule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-a-given-assignment-rule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-a-given-assignment-rule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update a given custom field value.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a given custom field value."}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}/values/{value_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a given custom field value.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-a-given-custom-field-value.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-a-given-custom-field-value.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-a-given-custom-field-value.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update a given custom field.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a given custom field."}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v3/explore_plus/assets/custom_fields/{custom_field_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a given custom field.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-a-given-custom-field.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-a-given-custom-field.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-a-given-custom-field.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update a given search.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update a given search."}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v3/explore_plus/assets/searches/{search_id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Update a given search.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-a-given-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-a-given-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-a-given-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update an individual search

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an individual search"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/v3/searches/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-search.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-search.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-search.StatusCodes.json")}
>
  
</StatusCodes>

---

## Perform analytics analysis

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Perform analytics analysis"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/analytics/analyze"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Execute analytics queries with support for nested analyses.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./analyze.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./analyze.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./analyze.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create export"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/content/export"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new content export job.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Mira response

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Mira response"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/mira/responses"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Generate AI-powered insights and responses.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-mira-response.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-mira-response.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-mira-response.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create stream

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create stream"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/content/stream"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Create a new content stream subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-stream.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-stream.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-stream.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete export

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete export"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/content/export/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete an export job.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete stream

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete stream"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/content/stream/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Delete a stream subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-stream.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-stream.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-stream.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get analytics catalog

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get analytics catalog"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/analytics/catalog"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get all available metrics and dimensions, optionally filtered by provider, metric type, or source.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-analytics-catalog.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-analytics-catalog.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-analytics-catalog.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get export details

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get export details"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/content/export/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get details of a specific export job.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-export.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-export.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-export.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get stream details

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get stream details"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/content/stream/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get details of a specific stream subscription.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-stream.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-stream.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-stream.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get metrics usage

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get metrics usage"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/usage/metrics"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get metrics usage statistics for the specified period.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-usage-metrics.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-usage-metrics.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-usage-metrics.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get API request usage

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get API request usage"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/usage/requests"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get API request usage statistics for the specified period.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-usage-requests.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-usage-requests.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-usage-requests.StatusCodes.json")}
>
  
</StatusCodes>

---

## Import documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Import documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/imports/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Import documents into Meltwater.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./import-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./import-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./import-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## List documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List documents"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of account documents.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-account-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-account-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-account-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## List companies

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List companies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/companies"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of companies accessible to the authenticated user.

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-companies.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-companies.StatusCodes.json")}
>
  
</StatusCodes>

---

## List custom categories

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List custom categories"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/assets/custom_categories"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of custom categories.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-custom-categories.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-custom-categories.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-custom-categories.StatusCodes.json")}
>
  
</StatusCodes>

---

## List custom fields

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List custom fields"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/assets/custom_fields"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of custom fields (Explore+).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-custom-fields.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-custom-fields.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-custom-fields.StatusCodes.json")}
>
  
</StatusCodes>

---

## List exports

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List exports"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/content/export"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of all content exports.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-exports.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-exports.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-exports.StatusCodes.json")}
>
  
</StatusCodes>

---

## List filter sets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List filter sets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/assets/filter_sets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of filter sets.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-filter-sets.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-filter-sets.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-filter-sets.StatusCodes.json")}
>
  
</StatusCodes>

---

## List import batches(V4)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List import batches"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/imports/batches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of import batches.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-import-batches.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-import-batches.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-import-batches.StatusCodes.json")}
>
  
</StatusCodes>

---

## List imported documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List imported documents"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/imports/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of imported documents.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-imported-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-imported-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-imported-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## List influencer campaigns

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List influencer campaigns"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/influencers/campaigns"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of influencer campaigns.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-influencer-campaigns.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-influencer-campaigns.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-influencer-campaigns.StatusCodes.json")}
>
  
</StatusCodes>

---

## List influencer tags

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List influencer tags"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/influencers/tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of influencer tags.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-influencer-tags.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-influencer-tags.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-influencer-tags.StatusCodes.json")}
>
  
</StatusCodes>

---

## List influencer workspaces

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List influencer workspaces"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/influencers/workspaces"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of influencer workspaces.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-influencer-workspaces.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-influencer-workspaces.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-influencer-workspaces.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Mira projects

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Mira projects"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/mira/projects"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of Mira projects.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-mira-projects.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-mira-projects.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-mira-projects.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Mira workflows

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Mira workflows"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/mira/workflows"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of Mira workflows.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-mira-workflows.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-mira-workflows.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-mira-workflows.StatusCodes.json")}
>
  
</StatusCodes>

---

## List monitored social connections

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List monitored social connections"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/social_connections/monitored"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of monitored social connections.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-monitored-connections.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-monitored-connections.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-monitored-connections.StatusCodes.json")}
>
  
</StatusCodes>

---

## List owned social connections

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List owned social connections"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/social_connections/owned"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of owned social account connections.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-owned-connections.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-owned-connections.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-owned-connections.StatusCodes.json")}
>
  
</StatusCodes>

---

## List paid social connections

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List paid social connections"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/social_connections/paid"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of paid social account connections.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-paid-connections.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-paid-connections.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-paid-connections.StatusCodes.json")}
>
  
</StatusCodes>

---

## List saved searches

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List saved searches"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/assets/searches"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of saved searches.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-searches.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-searches.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-searches.StatusCodes.json")}
>
  
</StatusCodes>

---

## List streams

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List streams"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/content/stream"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of all content streams.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-streams.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-streams.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-streams.StatusCodes.json")}
>
  
</StatusCodes>

---

## List tags

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List tags"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/assets/tags"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of tags.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-tags.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-tags.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-tags.StatusCodes.json")}
>
  
</StatusCodes>

---

## List workspaces

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List workspaces"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/account/workspaces"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Get a list of workspaces for the specified company.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-workspaces.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-workspaces.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-workspaces.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search content

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search content"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/content/search"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Perform a synchronous content search across specified data sources.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-content.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-content.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-content.StatusCodes.json")}
>
  
</StatusCodes>

---

## Custom Fields Management

# Explore+ Custom Fields

In this section, you'll learn how to use **custom fields** with **Explore+** when sending your own content via the Bring Your Own Content (BYOC) API.

## Custom Fields

Custom fields allow you to attach additional metadata to your documents when submitting them to the Meltwater API. These fields can be used to categorise, filter, and analyse your content within **Explore+**.

Only custom fields that have been pre-defined in **Explore+** can be included in the `customFields` array. Each custom field should have a `label` that matches the name of the field in **Explore+** and an array of `values`.

## Explore+ Setup

To utilise custom fields in **Explore+**, you need to set them up in your **Explore+** configuration before submitting documents via the BYOC API:

* Fields must be created in **Explore+** prior to submission.
* An Optimised query with `data collection` activated should be added to the project in **Explore+**:

```
metadata.provider.type:"byod"
```

## Attaching custom fields to your documents

When submitting documents to the Meltwater API, you can include custom fields by adding them to the `customFields` array in the document payload:

```json
{
  "documents": [
    {
      "title": "Sample Document",
      "content": "This is a sample document content.",
      "customFields": [
        {
          "label": "color",
          "values": ["red", "blue"]
        },
        {
          "label": "size",
          "values": ["large", "small"]
        }
      ]
    }
  ]
}
```

For more information on creating and managing custom fields in Explore+, see the [Explore+ Custom Fields Management](/guides/explore-plus/custom-fields-management) guide.

---

## Managing Imported Data


In this tutorial, you'll learn how to manage your imported data, including how to update and delete documents.

## Managing document unique identity

We recommend including an `id` field with every document, as it makes it easier to reliably reference the document later. If you plan to update or delete existing documents, you should always provide an `id`. **If provided, the value must be unique within the batch.**

If an `id` was not supplied, updates or deletions are still possible. However, in that case the following fields **must remain unchanged**:

* `content.title`
* `url`
* `originPlatform`
* `contentType`
* `id` (you cannot add an `id` retroactively)

If any of these identity fields are modified, we will not be able to match the original document. This will either create a duplicate (in the case of an update) or prevent deletion.

## Updating imported documents

To update a document, simply resubmit it with the same values for the identity fields listed above.

## Deleting imported documents

To delete a document, resend it (complete document) with the following property set:

```json
{
    "delete": true  
}
```

As with updates, the identity fields listed above must also remain unchanged.

---

## Monitoring Imported Data

# Monitoring Import Progress And Status

In this section, you'll learn how to monitor your imported data — the progress and status of documents you have submitted to the Meltwater API.

The Meltwater API `/imports/documents` returns a `batch_id` in the JSON response. You can use this `batch_id` to monitor the status of your imported documents.

A **Batch** is a group of documents that is imported together in a single API request.

## API Endpoints

The following endpoints are available to monitor your imported data.

### 1. List All Batches

Retrieve all batches for your company, filtered by time or status:

`GET /v3/imports/batches`

**Query Parameters:**
* `import_tag` (optional): Comma-separated list of values to filter batches by the `import_tag` value provided during document submission.
* `start` (optional): Start timestamp for filtering batches (ISO 8601 format without timezone).
* `end` (optional): End timestamp for filtering batches (ISO 8601 format without timezone).
* `tz` (optional): Timezone for interpreting the `start` and `end` input timestamps (default is UTC). This also determines the timezone for any timestamps in the output response.
* `status` (optional): Comma-separated list of statuses to filter by, e.g. `PENDING`, `FINISHED`, `FAILED`.
* `page` (optional): Page number for pagination (default is 1).
* `page_size` (optional): Number of items per page (default is 20, maximum is 100).
* `company_id` (optional): Meltwater company id if running a request on behalf of another company.

```shell
curl -X GET \
--url "https://api.meltwater.com/v3/imports/batches" \
--header "Accept: application/json" \
--header "apikey: **********"
```

Example response:

```json
{
   "content": [
      {
         "batch_id": "659d65a6-0937-406a-86da-9d2aa537dfef",
         "created_at": "2025-07-24T12:11:31Z",
         "import_tags": [
           "my-import-tag"
         ],
         "statistics": {
            "documents_sent": 2,
            "documents_indexed": 2,
            "documents_marked_duplicate": 0,
            "subgroups": {
               "social": {
                  "documents_indexed": 1,
                  "documents_marked_duplicate": 0
               },
               "editorial": {
                  "documents_indexed": 1,
                  "documents_marked_duplicate": 0
               }
            }
         },
         "status": "FINISHED"
      }
   ],
   "page": 1,
   "page_size": 1,
   "total": 1
}
```

* `documents_sent`: Number of documents sent (if available).
* `documents_indexed`: Number of documents indexed. This shows the quantity of documents that were successfully ingested into the Meltwater platform. These documents will appear in results if they match a query.
* `documents_marked_duplicate`: Number of documents marked as duplicate. These documents were identified as duplicates of existing documents in the Meltwater platform and were not indexed again. It currently only handles TikTok data. This is determined by the document's id or url. For other providers, this value will always be 0.
* `status`: The status of the batch, which can be one of:
  * `pending`: The batch is being processed.
  * `finished`: The batch is finished.
  * `failed`: The batch has failed.

### 2. Get Batch Status

Check the status and metrics for a specific batch using its `batchId`:

`GET /v3/imports/batches/{batch_id}`

```shell
curl -X GET \
--url "https://api.meltwater.com/v3/imports/batches/659d65a6-0937-406a-86da-9d2aa537dfef" \
--header "Accept: application/json" \
--header "apikey: **********"
```

Example response:

```json
{
   "batch_id": "659d65a6-0937-406a-86da-9d2aa537dfef",
   "created_at": "2025-07-24T12:11:31Z",
   "import_tags": [
     "my-import-tag"
   ],
   "statistics": {
      "documents_sent": 2,
      "documents_indexed": 2,
      "documents_marked_duplicate": 0,
      "subgroups": {
         "social": {
            "documents_indexed": 1,
            "documents_marked_duplicate": 0
         },
         "editorial": {
            "documents_indexed": 1,
            "documents_marked_duplicate": 0
         }
      }
   },
   "status": "FINISHED"
}
```

### 3. Get Import Tag Status

Check the status and metrics for a specific import tag using its `importTag`:

`GET /v3/imports/import_tags/{import_tag}`

```shell
curl -X GET \
--url "https://api.meltwater.com/v3/imports/import_tags/my-import-tag" \
--header "Accept: application/json" \
--header "apikey: **********"
```

Example response:

```json
{
   "created_at": "2025-07-24T12:11:31Z",
   "import_tag": "my-import-tag",
   "statistics": {
      "documents_sent": 2,
      "documents_indexed": 2,
      "documents_marked_duplicate": 0,
      "subgroups": {
         "social": {
            "documents_indexed": 1,
            "documents_marked_duplicate": 0
         },
         "editorial": {
            "documents_indexed": 1,
            "documents_marked_duplicate": 0
         }
      }
   },
   "status": "FINISHED"
}
```

---

## Overview(Bring-your-own-content)

# Bring Your Own Content (BYOC) Overview

The Meltwater platform ingests and enriches data from a wide variety of sources, including news and social platforms. With **Bring Your Own Content (BYOC)**, you can also ingest your own **first-party content** into the platform.

BYOC content is visible only to your company. Once ingested, it is stored in the same data schema as other Meltwater data and enriched with the same metadata (such as sentiment, language, and key phrases). This makes your content searchable and analyzable alongside Meltwater's global media coverage.

The API enables you to upload this content in JSON format, using a schema defined by Meltwater. Once uploaded, the content is indexed and available in the Meltwater application and API for analysis, dashboards, and reporting.

Because BYOC is a **push API**, ingestion is controlled by you. You decide what to send and when, whether in real-time, scheduled batches, or ad hoc uploads.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* Access to the Bring Your Own Content feature, which can be requested from Meltwater Support.

## API details to import documents

You can import documents by sending a POST request to the `/imports/documents` endpoint.

**Query Parameters:**
* `import_tag` (optional): Comma-separated list of string tags to label or group the batch of documents. This can help with tracking and filtering later using monitoring endpoints.
* `company_id` (optional): Meltwater company id if running a request on behalf of another company.

**Example document import format**

```json
{
    "documents": [
        {
            "id": "12345",
            "url": "http://example.com",
            "timestamp": 1748272125000,
            "content": {
                "title": "Example Title",
                "subtitle": "Example Subtitle",
                "text": "Example text content",
                "duration": 120
            },
            "originPlatform": "youtube",
            "contentType": "video",
            "attachments": [
                {
                    "name": "Attachment Name",
                    "url": "http://example.com",
                    "mime": "image/png",
                    "altText": "Alt text for the attachment",
                    "type": "image",
                    "thumbnail": "http://example.com"
                }
            ],
            "source": {
                "name": "The Meltwater Times",
                "url": "http://example.com",
                "location": {
                    "countryCode": "DE",
                    "locationString": "Berlin, Germany",
                    "coordinates": {
                        "lat": 52.52,
                        "lon": 13.405
                    }
                }
            },
            "user": {
                "name": "John Doe",
                "url": "http://example.com",
                "imageUrl": "http://example.com/avatar.png",
                "gender": "m",
                "location": {
                    "countryCode": "DE",
                    "locationString": "Berlin, Germany",
                    "coordinates": {
                        "lat": 52.52,
                        "lon": 13.405
                    }
                }
            },
            "parent": {
                "url": "http://example.com",
                "title": "Parent Document Title"
            },
            "metrics": {
                "views": 100,
                "audience": 50,
                "ave": 4.5,
                "score": 3.2,
                "likes": 50,
                "shares": 50,
                "comments": 50,
                "replies": 50
            },
            "sentiment": "positive"
        }
    ]
}
```

## Document fields

| Field | Required | Notes |
|-------|----------|-------|
| `id` | Optional | An id that you would like to use to identify the document during future requests (e.g. updates/deletes). **If provided, the value must be unique within the batch.** |
| `url` | Required | Article / post url |
| `timestamp` | Required | Epoch (in milliseconds) |
| `content` | Optional | |
| `content.title` | Optional | Title of the document |
| `content.subtitle` | Optional | Subtitle / ingress |
| `content.text` | Optional | Full text of the article / post |
| `content.duration` | Optional | Relevant for video/audio content (in seconds) |
| `originPlatform` | Required | See note [1] |
| `contentType` | Required | See note [2] |
| `attachments` | Optional | Items are objects with required subfields. Use for attaching additional media objects, like: images, videos, etc. |
| `attachments[].name` | Optional | Arbitrary name of the attachment |
| `attachments[].url` | Required | Url of the attachment |
| `attachments[].mime` | Required | Mime type |
| `attachments[].altText` | Optional | Alternative text / description. Usually for image / video attachments |
| `attachments[].type` | Required | See note [3] |
| `attachments[].thumbnail` | Optional | Thumbnail URL of the attachment, i.e. image thumbnail for video attachment |
| `source` | Required | |
| `source.name` | Required | Source name. If not applicable set it empty |
| `source.url` | Required | Url of the source, channel, etc. |
| `source.location` | Optional | |
| `source.location.countryCode` | Optional | ISO 3166-1 alpha-2 country code |
| `source.location.locationString` | Optional | Free text description of the location |
| `source.location.coordinates` | Optional | Contains required fields lat and lon |
| `source.location.coordinates.lat` | Required (if parent exists) | Geo latitude (numeric, decimal) |
| `source.location.coordinates.lon` | Required (if parent exists) | Geo longitude (numeric, decimal) |
| `user` | Optional | User / author / presenter / speaker. Name or handle must be present |
| `user.name` | Required if handle not supplied | User / author / presenter / speaker full name |
| `user.handle` | Required if name not supplied | Intended mainly for social |
| `user.url` | Optional | User / author / presenter / speaker profile url |
| `user.imageUrl` | Optional | User / author / presenter / speaker profile image url |
| `user.gender` | Optional | See note [4] |
| `user.location` | Optional | |
| `user.location.countryCode` | Optional | ISO 3166-1 alpha-2 country code |
| `user.location.locationString` | Optional | Free text description of the location |
| `user.location.coordinates` | Optional | Contains required fields lat and lon |
| `user.location.coordinates.lat` | Required (if parent exists) | Geo latitude (numeric, decimal) |
| `user.location.coordinates.lon` | Required (if parent exists) | Geo longitude (numeric, decimal) |
| `parent` | Optional | Parent entity of this document - parent post, etc. |
| `parent.url` | Optional | Url of the parent post |
| `parent.title` | Optional | Title of the parent post |
| `product` | Optional | Mainly for product reviews |
| `product.name` | Optional | Product name |
| `metrics` | Optional | |
| `metrics.views` | Optional | View / impression count |
| `metrics.audience` | Optional | Audience / reach for given source |
| `metrics.ave` | Optional | Advertising Value Equivalency |
| `metrics.score` | Optional | Mainly for product reviews and voice of customers. Review score. |
| `metrics.likes` | Optional | Likes count |
| `metrics.shares` | Optional | Shares count |
| `metrics.comments` | Optional | Comments count |
| `metrics.replies` | Optional | Replies count |
| `sentiment` | Optional | Sentiment of the document. See note [5] |
| `customFields` | Optional | Explore+ custom fields. See note [6] |

**Notes on fields**

[1] `originPlatform` possible values:
`youtube`, `podcasts`, `facebook`, `instagram`, `reddit`, `sina_weibo`, `wechat`, `twitter`, `linkedin`, `pinterest`, `twitch`, `tiktok`, `douyin`, `little_red_book`, `youku`, `bilibili`, `threads`, `kakaotalk`, `linevoom`, `discord`, `snapchat`, `bluesky`, `news_publisher`, `broadcast`, `tender_portal`, `reviews`, `blogs`, `forums`, `social_comments`, `telegram`

[2] `contentType` possible values:
`video`, `comment`, `repost`, `reply`, `quoted`, `audio`, `post`, `online_press`, `print_press`, `tender`, `product_review`, `voc`
Note: Values must match platform-specific rules.

[3] `attachments[].type` possible values:
`image`, `audio`, `video`

[4] `user.gender` possible values:
`m` (male), `f` (female), `n` (other)

[5] `sentiment` possible values:
`neutral`, `positive`, `negative`, `unknown`

[6] For using Explore+ custom fields, see the [Explore+ Custom Fields](/guides/bring-your-own-content/custom-fields-management) guide.

## JSON schema

A schema for validating individual documents is available here: [BYOC JSON schema](pathname:///byoc-json-schema.json)

## Sending the documents

Suppose that you save a set of documents as defined above into a file named `documents.json`.

Then to upload that file with `curl` you can execute:

```shell
curl -X POST \
--url "https://api.meltwater.com/v3/imports/documents" \
--header "Accept: application/json" \
--header "apikey: **********"
--data @documents.json
```

You can also submit documents on behalf of another Meltwater company you're authorised for. For more information on working with multiple Meltwater companies, see the [Multiple Companies guide](/guides/getting-started/multiple-companies).

## API Limitations

* Maximum 500 documents per request
* Maximum 25MB payload size per request
* [General API call limits](/guides/getting-started/usage-limits)

## Verification

If all goes well, you will receive a response providing a batch ID and a count of the uploaded documents:

```json
{
    "batchId": "3ccd4b7f-5987-45ca-a774-7be330763489",
    "count": 20
}
```

It is possible to track the progress of your batch using [Monitoring APIs](/guides/bring-your-own-content/monitoring-imported-data). Alternatively, you can also check your documents in the Meltwater app.

To find all documents that you have imported via this API, you can query like this:

`metaData.provider.type:"byod"`

To find the documents using the supplied `batchId` from the response, you can query like this:

`metaData.applicationTags:"byod:batchId={batchId}"`

If you supplied your own `id` field on the documents, you can find them individually like this:

`externalId:{id}`

We recommend including an `id` field with every document, as in general it makes it easier to reliably find it later on. Otherwise you may need to search on some other known pieces of information from the documents (e.g. title).

## Frequently Asked Questions

For answers to common questions, see the [BYOC FAQ](/help/faqs).

---

## Analyzing Mentions


In this tutorial we'll cover the basics of analyzing mentions from Explore+ using the API.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* An Optimized Search in your Explore+ instance

## Listing your Optimized Searches

To analyze mentions you will need to provide one or more search IDs to the API analysis endpoint.

You can use the `GET /v3/explore_plus/assets/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The `workspace_id` parameter is mandatory. As explained in the [Explore+ API overview](/guides/explore-plus/overview), use `none` as the value if you want to access assets at the account-level, or a workspace id if you want to access assets in a specific workspace.

You'll use the `id` field for searches in your analytics requests to the API.

## Analyzing mentions

You can use the `POST /v3/explore_plus/analytics/custom` endpoint to perform analysis requests.

Here's an example request which we'll break down below in detail, given the number of options available:

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/analytics/custom?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "searches": {
    "all": [123],
    "any": [],
    "none": []
  },
  "start": "2024-10-01T00:00:00",
  "end": "2024-10-08T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  }
}'
```

### Time period

For each request you must specify a time window using the following parameters:

* `start` and `end` - The time period you'd like to analyze (ISO8601 timestamps, excluding timezone/offset). Note that the result will be inclusive of the start time and exclusive of the end time.
* `tz` - An identifier from the [IANA database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), or a timezone offset, from UTC.

**The maximum time range for an analysis is 12 months.**

### Searches

For each request you must also specify the searches you'd like to be processed.

To specify searches use the ID of each search within the following fields:

* `all` - results must be in all these searches
* `any` - results can be in any of these searches
* `none` - exclude results from these searches

### Filters

You can optionally apply standard filters and filters based upon your custom fields.

To specify filters you can use the following fields in your request:

* `sources` - the source(s) you'd like to analyze
* `languages` - A primary language subtag from the IANA language tag registry
* `countries` - The two-letter ISO 3166-1 Alpha-2 country code, or `ZZ` for unknown
* `sentiments` - `positive`, `negative`, or `neutral`
* `custom_fields` - Filters for results that match the given Custom Field's values

*For more information on Custom Fields see the [Managing Custom Fields](/guides/explore-plus/custom-fields-management) guide.*

## Analysis types

The API supports the following analysis types:

* `document_count` - The total number of mentions
* `top_terms` - Breaks down mentions by a dimension, for example by sentiment
* `date_histogram` - Breaks down mentions by date, for example by day or month
* `measure_statistic` - Returns the total (sum) for one or more measurements

The API also supports nested analysis with the following possible combinations:

* `date_histogram` -> `measure_statistics`
* `date_histogram` -> `top_terms`
* `date_histogram` -> `top_terms` -> `measure_statistics`
* `date_histogram` -> `top_terms` -> `top_terms`
* `date_histogram` -> `top_terms` -> `top_terms` -> `measure_statistics`
* `top_terms` -> `measure_statistics`
* `top_terms` -> `top_terms`
* `top_terms` -> `top_terms` -> `measure_statistics`
* `top_terms` -> `top_terms` -> `top_terms`
* `top_terms` -> `top_terms` -> `top_terms` -> `measure_statistics`

## Supported measures and dimensions

See the [analytics options](/api-reference/analytics-options/explore-plus) page for details of which measures and dimensions are supported.

## Document count analysis

```json
{
  "searches": { "any": [123] },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": { "type": "document_count" }
}
```

Example response:

```json
{
  "result": { "document_count": 3241 }
}
```

## Top terms analysis

```json
{
  "searches": { "any": [123] },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "top_terms",
    "dimension": "language",
    "limit": 10
  }
}
```

Example response:

```json
{
  "result": {
    "document_count": 3243,
    "analysis": [
      { "key": "EN", "label": "English", "document_count": 2207, "percentage": 68.05 },
      { "key": "FR", "label": "French", "document_count": 324, "percentage": 9.99 }
    ]
  }
}
```

### Top terms analysis with Custom Fields

You can perform a top terms analysis on a custom field using the `custom_field` dimension:

```json
{
  "analysis": {
    "type": "top_terms",
    "dimension": "custom_field",
    "custom_field_id": 456
  }
}
```

### Top terms analysis with searches

Aggregate how many documents matched each given search:

```json
{
  "analysis": {
    "type": "top_terms",
    "dimension": "search",
    "searches": [123, 456]
  }
}
```

## Date histogram analysis

```json
{
  "searches": { "any": [123] },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day"
  }
}
```

The `granularity` parameter supports:

* `hour` - time windows up to 7 days
* `day` - time windows up to 30 days
* `week` - time windows up to 1 year
* `month` - time windows up to 1 year

## Measure statistic analysis

```json
{
  "searches": { "any": [123] },
  "start": "2024-01-01T00:00:00",
  "end": "2024-01-15T00:00:00",
  "tz": "UTC",
  "analysis": {
    "type": "measure_statistics",
    "measures": ["engagement"]
  }
}
```

Example response:

```json
{
  "result": {
    "document_count": 3243,
    "analysis": {
      "engagement": { "sum": 88229 }
    }
  }
}
```

## Nested analysis example

The following example performs a date histogram analysis with a nested top terms analysis, analyzing the number of mentions by day, further broken down by language:

```json
{
  "searches": { "any": [5135] },
  "start": "2024-12-06T00:00:00",
  "end": "2025-01-05T00:00:00",
  "tz": "Europe/Amsterdam",
  "analysis": {
    "type": "date_histogram",
    "granularity": "day",
    "analysis": {
      "type": "top_terms",
      "dimension": "language"
    }
  }
}
```

Example response:

```json
{
  "result": {
    "document_count": 1439,
    "analysis": [
      {
        "key": "2024-12-06T00:00:00",
        "document_count": 48,
        "percentage": 3.34,
        "analysis": [
          { "key": "EN", "label": "English", "document_count": 24, "percentage": 50.00 },
          { "key": "ES", "label": "Spanish", "document_count": 9, "percentage": 18.75 }
        ]
      }
    ]
  }
}
```

---

## Managing Custom Fields


In this guide we'll cover the basics of creating, updating and deleting Custom Fields in Explore+ using the API.

Note that Custom Fields are constructed as follows:

* Custom field (with name, description and type)
    * Values (for tag fields one value, for multi-value fields multiple values)
        * Assignment rules (for each value multiple assignment rules can exist)

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token

## Custom Field folders

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/folders?workspace_id=none&page_size=10&page=1" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

## Listing Custom Fields

```shell
curl --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields?workspace_id=none&page_size=10&page=1' \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "page": 1,
  "page_size": 10,
  "total": 30,
  "custom_fields": [
    {
      "id": 123,
      "folder_id": 456,
      "name": "My Custom Field",
      "description": "This is my Custom Field",
      "created": "2024-01-01T00:00:00Z",
      "updated": "2024-01-01T00:00:00Z",
      "type": "multi_value"
    },
    {
      "id": 456,
      "folder_id": null,
      "name": "My Custom Field 2",
      "type": "tag"
    }
  ]
}
```

## Getting Custom Field details

```shell
curl --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response includes the field's values with IDs you can use for subsequent API calls.

## Creating a Custom Field

Two types supported: `tag` (single value, auto-created) and `multi_value` (multiple values).

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "custom_field": {
    "name": "My Custom Field",
    "description": "my new Custom Field",
    "folder_id": 123,
    "type": "tag"
  }
}'
```

Parameters: `name`, `description`, `folder_id`, `type`.

## Updating a Custom Field

```shell
curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/1345?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "custom_field": {
    "name": "My Custom Field - Updated",
    "description": "My new description",
    "type": "tag"
  }
}'
```

Note: you cannot change the type of a Custom Field once created.

## Deleting a Custom Field

```shell
curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Returns `204` on success.

## Getting Custom Field Value details

```shell
curl --request GET \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/987?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

## Creating a Custom Field value

Note: you cannot add a value to a tag type field (it has one auto-created value).

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "custom_field_value": {
    "name": "My Custom Field Value",
    "color": "#FFFFFF"
  }
}'
```

## Updating a Custom Field value

```shell
curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "custom_field_value": {
    "name": "My Custom Field Value - Updated",
    "color": "#FFFFFF"
  }
}'
```

## Deleting a Custom Field value

```shell
curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123/values/456?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

## Creating a Custom Field Value assignment rule

Two types of rule supported: `boolean` and `keyword`.

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123/rules?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "rule": {
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}'
```

For keyword rules, use `all_keywords`, `any_keywords`, `not_keywords` and `case_sensitivity`.

## Updating a Custom Field value assignment rule

```shell
curl --request PUT \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/custom_fields/12345/values/123/rules/456?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "rule": {
    "query": {
      "case_sensitivity": "no",
      "boolean": "honda OR mazda",
      "type": "boolean"
    }
  }
}'
```

## Deleting a Custom Field value assignment rule

```shell
curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/custom_fields/123/values/456/rules/789?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Returns `204` on success.

---

## Managing Searches


In this tutorial we'll cover the basics of creating, updating and deleting searches in Explore+ using the API.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token

## Search folders

In Explore+ folders are used to organize searches in your account. To fetch the folders configured in your account you can call the `GET /v3/explore_plus/assets/searches/folders` endpoint:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/folders?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The `workspace_id` parameter is mandatory. Use `none` for account-level assets, or a workspace ID for assets in a specific workspace.

The endpoint supports pagination with `page`, `page_size` (default 10, max 100), and `show_hidden` (default false).

Example response:

```json
{
  "page": 1,
  "page_size": 10,
  "total": 2,
  "folders": [
    {
      "id": 123,
      "name": "My Search Folder",
      "color": "#FFFFFF",
      "created": "2025-01-01T00:00:00Z",
      "updated": "2025-01-01T00:00:00Z",
      "num_searches": 1,
      "parent": null,
      "hidden": false
    }
  ]
}
```

As folders can be nested in Explore+ you can use the `parent` field in the response to understand the relationship between folders.

## Listing searches

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Optional parameters: `page`, `page_size` (max 100), `folder_id`, `show_hidden` (default false).

## Getting search details

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "search": {
    "id": 123,
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "created": "2025-01-01T00:00:00Z",
    "updated": "2025-01-01T00:00:00Z",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false,
    "data_collection_updated": "2025-01-01T00:00:00Z",
    "hidden": false
  }
}
```

## Creating a search

Call the `POST /v3/explore_plus/assets/searches` endpoint. Three types of search are supported: `boolean`, `keyword`, and `combined`.

Parameters: `name`, `description`, `color` (hex), `folder_id`, `data_collection`, `query.type`.

### Boolean searches

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "search": {
    "folder_id": null,
    "name": "My Search",
    "description": "my first search",
    "color": "#FFFFFF",
    "query": {
      "case_sensitivity": "yes",
      "boolean": "honda OR mazda",
      "type": "boolean"
    },
    "data_collection": false
  }
}'
```

`case_sensitivity` options: `yes` (exact match), `no` (case insensitive), `hybrid` (match capital letters only).

### Keyword searches

```shell
--data '{
  "search": {
    "name": "My Search",
    "query": {
      "case_sensitivity": "yes",
      "all_keywords": ["honda"],
      "any_keywords": ["mazda"],
      "not_keywords": ["nissan"],
      "type": "keyword"
    },
    "data_collection": false
  }
}'
```

### Combined searches

```shell
--data '{
  "search": {
    "folder_id": 123,
    "name": "My Search",
    "query": {
      "all_searches": [{"id": 123, "type": "SEARCH"}],
      "any_searches": [{"id": 456, "type": "SEARCH"}],
      "not_searches": [{"id": 789, "type": "SEARCH"}],
      "type": "combined"
    },
    "data_collection": false
  }
}'
```

## Updating a search

Call the `PUT /v3/explore_plus/assets/searches/<search_id>` endpoint with the same fields as creation. Note that you cannot change the type of a search in an update.

## Deleting a search

```shell
curl -X DELETE \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches/123?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Returns a `204` status code on success.

---

## Overview(Explore-plus)


In this guide we'll introduce you to key Listening concepts of Explore+ and how it fits with the wider Meltwater platform and API.

## Meltwater platform

The **Meltwater platform** ingests and enriches data from a wide variety of sources, including news and social platforms. Data is enriched by a set of enrichments (sentiment, language, key phrases, etc.) and stored in a consistent data schema. Listening data is held in a central store. Using the listening features of the Meltwater API you can export, stream and analyze the data held in this central index.

Learn more about listening features [here](/guides/listening/overview).

## Explore+

Customers with access to Explore+ have a private data index hosted by Meltwater, which is filled using searches that collect mentions from the central listening platform, but allow customers to add their own business context. For example, an Explore+ customer can add data structuring and classifications to listening data (such as their brands and products).

Explore+ customers also benefit from additional enrichments upon data in their index, depending on their exact package.

Given the additional data structuring and additional enrichments, Explore+ can perform more in-depth, custom analysis.

## Explore+ API

The Explore+ API features allow you to access this same in-depth analysis, and structured, enriched content.

For example you can pull out content, filtered by your custom data structuring. Or perform analysis filtered by your own custom fields.

Note that broadly speaking you can access the same data through the API as a user sees in the application. However, due to the agreements we have with data providers there are some limitations on what data can be provided through the API.

*For example, in the application we can provide the text of X posts, whereas due to X's terms of service in the API we can only provide the ID of a post. An API customer needs to call the X API to rehydrate the post in order to get the post text.*

## Workspaces

Explore+ Workspaces allow customers to organize their assets to match their organization. Assets such as searches and custom fields exist either at the account level, or within a Workspace within an account.

When you access assets using the Explore+ API, you will need to provide the `workspace_id` parameter in your API calls to ensure you are accessing assets at the account level or in a Workspace.

To access assets at the account level set the `workspace_id` to `none`. To access assets in a Workspace, set the `workspace_id` to the Workspace ID.

## Optimized Searches

Optimized Searches in Explore+ are similar to Explore saved searches, in that they can be created with keywords and boolean, but it is these searches that also define what data is collected into your private Explore+ index.

An Optimized Search can be created in the Meltwater application using the **Explore+** product, or by using the API.

Typically this will be a boolean query. For example, if you wanted to find news articles or social posts that mention Apple watches you may write:

`(apple AND (iphone OR iwatch)) NOT ("apple sauce" OR "apple juice" OR "apple orchard*")`

You may already have searches saved in the Explore+ application that you'd like to use with the API. If you'd like to create searches using the API take a look at the [Managing Saved Searches](/guides/explore-plus/managing-searches) guide.

## Custom Fields

Custom Fields allow you to define your own content categorizations with predefined values.

There are 2 types of Custom fields:

- **Tag fields** - allow you to tag posts based on one or more boolean rules.
- **Multivalued fields** - A multivalued field allows you to precisely tag data based on a list of predefined values. Each value is assigned based on one or more boolean rules.

You may already have fields configured in the Explore+ application that you'd like to use with the API. If you'd like to create or manage fields using the API take a look at the [Managing Custom Fields](/guides/explore-plus/custom-fields-management) guide.

## Searching mentions

Using the API you can search and fetch mentions stored in your Explore+ index. You could fetch the same mentions using the API listening features, but these wouldn't be returned with any custom fields you have configured in your Explore+ account.

You search mentions by providing a time range, one or more Optimized Searches, and optionally additional filters. The API will return any matching mentions, sorted by the sort parameter you provide.

The fields available for documents depend on the source of the document and the template you choose for your export. See the [Content Output Templates](/api-reference/templates/overview) page for full details.

To learn how to search mentions using the API see the [Searching Mentions guide](/guides/explore-plus/searching-mentions).

## Analyzing mentions

Using the API you can run analysis on mentions in your Explore+ index. You can recreate the same widgets you see in Explore+ dashboards using the API. The API will analyze any matching mentions based on the type of analysis you have requested.

For example, you could request a breakdown of the number of mentions over time.

You run an analysis by providing a time range, one or more Optimized Searches, and optionally additional filters. You then specify a type of analysis (such as a date histogram), and additional dimensions or metrics as appropriate for the analysis type.

To understand what analytics are available see the [Analytics Options](/api-reference/analytics-options/explore-plus) page.

To learn how to request analytics using the API see the [Analyzing Mentions guide](/guides/explore-plus/analyzing-mentions).

## Tagging mentions

You can apply your own tags to documents to help structure & classify data for your organization.

See our [Tagging Mentions](/guides/listening/tagging-earned-media) guide to learn more.

Documents tagged as described by the guide will be available in both your Explore and Explore+ environments.

---

## Searching Mentions


In this tutorial we'll cover the basics of searching and fetching mentions from Explore+ using the API.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* An Optimized Search in your Explore+ instance

## Listing your Optimized Searches

Unless you have a set of specific mention IDs to fetch, to search mentions you will need to provide one or more search IDs to the API search endpoint.

You can use the `GET /v3/explore_plus/assets/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/explore_plus/assets/searches?workspace_id=none" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The `workspace_id` parameter is mandatory. As explained in the [Explore+ API overview](/guides/explore-plus/overview), use `none` as the value if you want to access assets at the account-level, or a workspace id if you want to access assets in a specific workspace.

Note that the endpoint supports the following optional parameters:

* `page` - the page of results to fetch. Defaults to `1`.
* `page_size` - the number of searches to fetch. Defaults to `10`, max is `100`.

Example response:

```json
{
  "page": 1,
  "page_size": 10,
  "total": 12,
  "searches": [
    {
      "id": 123,
      "folder_id": 456,
      "name": "My Search",
      "description": "This is my search",
      "updated": "2024-01-01T00:00:00Z",
      "type": "keyword",
      "query": {},
      "data_collection": false,
      "data_collection_updated": "2024-01-01T00:00:00Z",
      "hidden": false
    }
  ]
}
```

You'll use the `id` field for searches in your search requests to the API.

## Search output options

Before we look at some example search requests, let's take a look at the output options supported by the API.

For a search request you can use the following parameters:

* `template` - The template you wish the documents to be formatted in. Defaults to `api.json`.
* `page` - the page of results to fetch. Defaults to `1`.
* `page_size` - the number of results to fetch. Defaults to `10`, max is `1000`.
* `sort_by` - The sort field of results, one of `date`, `reach`, `engagement`, `social_echo`, `relevance`, `prominence`, or `views`. Defaults to `date`.
* `sort_order` - The sort order of results, either `asc` (ascending) or `desc` (descending). Defaults to `desc`.

*See the [Content Output Templates](/api-reference/templates/overview) page for full details of fields included in output templates.*

As an example the following parameters would fetch the first page of 100 results, ordered by date descending, and output results using the `api.json` template.

```json
{
    "page": 1,
    "page_size": 100,
    "sort_by": "date",
    "sort_order": "desc",
    "template": {
        "name": "api.json"
    }
}
```

## Searching mentions using Optimized Searches

You can use the `POST /v3/explore_plus/search` endpoint to fetch mentions based upon your searches.

Here's an example request which we'll break down below in detail, given the number of options available:

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/search?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "searches": {
    "all": [123],
    "any": [],
    "none": []
  },
  "start": "2024-10-01T00:00:00",
  "end": "2024-10-08T00:00:00",
  "page": 1,
  "page_size": 100,
  "sort_by": "date",
  "sort_order": "desc",
  "tz": "UTC",
  "template": {
    "name": "api.json"
  }
}'
```

### Time period

For each request you must specify a time window using the following parameters:

* `start` and `end` - The time period you'd like to analyze (ISO8601 timestamps, excluding timezone/offset). Note that the result will be inclusive of the start time and exclusive of the end time.
* `tz` - An identifier from the [IANA database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), or a timezone offset, from UTC.

**The maximum time range for a search is 12 months.**

Please note that you can paginate up to 10,000 mentions for any specific time period. To access more than 10,000 results, you will need to split your requests into smaller time ranges.

### Searches

For each request you must also specify the searches you'd like to be processed.

To specify searches use the ID of each search within the following fields:

* `all` - results must be in all these searches
* `any` - results can be in any of these searches
* `none` - exclude results from these searches

For example the following parameters will include mentions that match any of the two searches (123, 456) but exclude mentions which appear in the search 789.

```json
{
    "searches": {
        "all": [],
        "any": [123, 465],
        "none": [789]
    }
}
```

Searching for mentions with a hidden search is not supported. If you include a hidden search in your request, you will receive a `404` Not Found error response.

### Filters

When searching you can optionally apply standard filters and filters based upon your custom fields.

To specify filters you can use the following fields in your request:

* `sources` - the source(s) you'd like to analyze, for example, `news` or `blogs`. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
* `languages` - A primary language subtag from the IANA language tag registry, `zh-Hant`, `zh-Hans`, or `zz`.
* `countries` - The two-letter ISO 3166-1 Alpha-2 country code, or `ZZ` for unknown.
* `sentiments` - The sentiment of the results. Possible values are `positive`, `negative`, and `neutral`.
* `custom_fields` - Filters for results that match the given Custom Field's values.

*For more information on Custom Fields, including how to fetch the IDs of fields for use in searching mentions see the [Managing Custom Fields](/guides/explore-plus/custom-fields-management) guide.*

For each of these fields you can combine multiple values using 'all', 'any' and 'none'.

For example, these parameters would include all languages except French and German, include only positive and neutral documents, and filter to documents that match value with ID 123 from your custom field with ID 456:

```json
{
    "filters": {
        "languages": {
            "none": ["de", "fr"]
        },
        "sentiments": {
            "any": ["positive", "neutral"]
        },
        "custom_fields": {
            "456": {
                "all": [123]
            }
        }
    }
}
```

## Fetching mentions by ID

You can also use the same API endpoint to fetch mentions by ID. This might be useful for example if you want to check for updates on specific mentions in your index.

To do so you need to specify the IDs of mentions to fetch using the `doc_ids` parameter.

For example, here's a request to fetch three documents, formatted with the `api.json` template:

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/explore_plus/search?workspace_id=none' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "doc_ids": [
    "abcD23423aAScasava",
    "fbgD23423aASca405v",
    "dkfD23423a53Agkssc"
  ],
  "page": 1,
  "page_size": 100,
  "sort_by": "date",
  "sort_order": "desc",
  "tz": "UTC",
  "template": {
    "name": "api.json"
  }
}'
```

## Understanding search results

Mentions will be returned by the API in the following structure:

```json
{
  "documents": [
    {
      "author": {
        "external_id": "123456789987654321"
      },
      "content": {
        "body": "this is an example document"
      }
    }
  ],
  "count": 1
}
```

You'll receive an array of documents (mentions) at the top level, plus an overall count of mentions that match your search, which you can use to paginate through if necessary.

---

## Accessing Usage Statistics


To understand your usage of API features you can access usage statistics both in the Meltwater application, and through the API directly.

## Viewing usage in the Meltwater application

Log into the [Meltwater application](https://app.meltwater.com), then navigate to the Meltwater API page (under the Account menu).

At the top of the Meltwater API page you will see a section named API Usage. Click on **See All Usage** to continue.

On the Usage Data page you will see multiple charts. You can use the date range selector in the top right to select a time period to view usage for.

The charts on this page include:

* **Earned Media Exports** - The number of earned media exports you have run
* **Earned Media Documents** - The number of earned media documents you have retrieved from the platform
* **Earned Media Analytics** - The API calls you have made to earned media analytics features
* **Owned Social Analytics** - The number of owned social analytics calls broken down by each analytic endpoint

After loading this page, there is a dropdown menu at the top labelled `All Tokens`. This indicates that the charts shown include usage across all API tokens in the company. Clicking on the dropdown menu and selecting a token will update the charts to display usage for that specific token:

Per-token usage data is available from 3 March 2026 onwards. Usage prior to this date is not broken down by token.

If you do not see the expected token based document count usage for an existing recurring export or stream, then you may need to re-create the recurring export or stream. This will allow any new document count usage to be tracked against the token.

We currently only track `Uploaded Documents` usage in `All Tokens` but not under individual tokens.

You can use the API to fetch more detailed statistics, but these charts should help you understand your usage of the main API features.

## Accessing usage statistics using the API

You can fetch statistics for your API usage from the [API usage endpoints](/api-reference/api-reference-overview). The data available from the usage endpoints allows you to keep an eye on your [usage limits](/guides/getting-started/usage-limits).

### Usage periods

The `period` parameter is common to all the usage endpoints. This parameter can take one of the following values:

* `24hours` - returns the last 24 hours of usage data, broken down by hour
* `7days` - returns the last 7 days of usage data, broken down by day
* `30days` - returns the last 30 days of usage data, broken down by day
* `12months` - returns the last 12 months of usage data, broken down by month

### Earned media exports

#### Exports per month

If you have access to the export feature, you may be subject to a limit on the number of exports you can run in a month.

You can fetch the number of exports you have run by using the `GET usage/me/metrics` endpoint, specifying the `export_count` metric and the `exports` feature.

For instance to fetch the number of exports you have run in the last 30 days:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/metrics/export_count?feature=exports&period=30days" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

An example response is:

```json
{
    "units": "day",
    "count": 56,
    "feature": "exports",
    "metric": "export_count",
    "period": "30days",
    "time_series": [
        {
            "timestamp": "2021-09-21T00:00:00Z",
            "count": 2
        },
        {
            "timestamp": "2021-09-20T00:00:00Z",
            "count": 2
        },
        ...
    ]
}
```

The returned fields are:

- `feature`: the feature requested
- `metric`: the metric requested
- `count`: the total usage for the requested period (in this case the total number of exports)
- `units`: the time unit used for the breakdown of metrics
- `time_series`: the breakdown of usage, where `count` is the usage within each time period (in this case the number of exports)

#### Documents per month

If you have access to the export or data streaming feature, you are subject to a limit on the number of documents you can export in a month.

For exports, you can fetch the number of documents you have exported by using the `GET usage/me/metrics` endpoint, specifying the `document_count` metric and the `exports` feature.

For searches, you can fetch the number of documents you have received by using the `GET usage/me/metrics` endpoint, specifying the `document_count` metric and the `search` feature.

For data streaming, you can fetch the number of documents you have streamed by using the `GET usage/me/metrics` endpoint, specifying the `document_count` metric and the `streaming` feature.

An example call for `exports` is shown below:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/metrics/document_count?feature=exports&period=30days" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

An example call for `search` is shown below:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/metrics/document_count?feature=search&period=30days" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

An example call for `streaming` is shown below:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/metrics/document_count?feature=streaming&period=30days" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

An example response is:

```json
{
    "units": "day",
    "count": 19044,
    "feature": "exports",
    "metric": "document_count",
    "period": "30days",
    "time_series": [
        {
            "timestamp": "2021-09-21T00:00:00Z",
            "count": 2438
        },
        {
            "timestamp": "2021-09-20T00:00:00Z",
            "count": 1756
        },
        ...
    ]
}
```

The fields are the same as explained before, except that the `count` field in this case reflects the number of documents exported.

### Earned media analytics & search

*The recently added [earned media search feature](/guides/listening/searching-mentions) is limited in the same way as earned media analytics features. Calls to the search feature are counted towards your daily analytics call limit.*

#### Daily calls

If you have access to analytics through the API you will be limited to a number of analytics calls per day.

You can fetch the number of analytics requests you have made by using the `GET usage/me/requests` endpoint. This returns the number of requests you have made to all API endpoints.

For instance to fetch the number of API calls you have made in the last 30 days:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/requests?period=30days" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

An example response is:

```json
{
    "units": "day",
    "count": 60,
    "time_series": [
        {
            "timestamp": "2021-09-21T00:00:00Z",
            "calls": {
                "v3": {
                    "analytics": {
                        "summary": {
                            "count": 1
                        },
                        "top-keyphrases": {
                            "count": 1
                        }
                    },
                    ...
                }
            }
        },
        ...
    ]
}
```

The returned fields are:

- `units`: the time unit used for the breakdown of the metrics
- `count`: the total usage for the requested period (in this case the total number of all API requests)
- `time_series`: the breakdown of API call usage

Within each item of the timeseries the response includes the usage for each API endpoint. So in the example above the analytics summary endpoint was hit once within the report period.

### All API calls (including Owned Social analytics and Explore+ API features)

You can make the same call as explained in the **Daily analytics calls** section above. This will return details for all your calls to API endpoints.

The `GET usage/me/requests` endpoint returns your API usage for all API endpoints. You can use the same request shown above for analytics calls to look at your usage.

### Filtering by API Token

All usage endpoints accept an optional `token_id` query parameter. When provided, the response will only include usage for the specified API token. If omitted, usage across all API tokens in the company is returned.

You can find the ID of each API token by using the [list tokens endpoint](/api-reference/api-reference-overview).

For example, to fetch export usage for a specific API token:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/usage/me/metrics/export_count?feature=exports&period=30days&token_id=YOUR_TOKEN_ID" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

---

## API Credentials


## Managing tokens in the Meltwater application

Users with 'Admin' level access for the Meltwater API permission can manage API tokens inside the main Meltwater application on the [Meltwater API page](https://app.meltwater.com/a/meltwater-api).

To manage your API token go to **Account** > **Meltwater API** in the application left-hand navigation.

## Create an API token

If you do not have an existing API token, click **Create Token**:

Now enter a name for the token. Choose a name that is useful for your reference:

Click **OK**, and wait for the token to be generated. Once it is generated the token will be shown:

Make sure you copy the token at this point as you will not be able to access the token in future for security reasons.

You will use this token as the value of the `apikey` header when calling the API.

Your token will now be listed on the Meltwater API page:

## Revoke an API token

You may want to revoke your API token if you are concerned it has been compromised, or if you want to ensure any services you have running cannot consume your API allowances.

Click on the **Revoke** button () next to the listed token, and confirm that you would like to proceed:

The token will be invalidated and any API requests made with this token will fail.

## Viewing token usage details

Click on the **See Usage** button () to see consumption for API tokens. For further information, see the [Accessing Usage Statistics](/guides/getting-started/accessing-usage-statistics) page.

---

## Multiple Companies


Most Meltwater customers have one **company**. This company is associated with their API package, API token, and with the searches they create in the application and API.

If you have access to multiple companies then you have a **default company** which is associated to your API package and API token, but you can access the searches for your default company and other companies you have access to.

For earned media features you can use the API to manage the searches of the companies you have access to, plus you can use these searches to export and analyze content.

For owned social features you can use the API to access metrics and analytics for the social accounts of the companies you have access to.

## Limits and content restrictions

When you call the API limits are applied according to the package of your **default company**

Note that for earned media features any content restrictions that are applied relate to the company that owns the search you are using. For example, if your **default company** is based in the US, but the company that owns the search is based in Australia, the content provided by the API will have content rules applied for Australian customers.

## Fetching companies from the API

To access searches of your multiple companies you need to know the IDs of these companies.

You can fetch companies using the `/accounts/me/companies` endpoint. See the [endpoints specification](/api-reference/api-reference-overview) for details.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/accounts/me/companies" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

This endpoint returns the companies you have access to:

```json
{
  "companies": [
    {
      "name": "Your company",
      "id": "61d07a1eb6b...."
    },
    {
      "name": "2nd company",
      "id": "61d07a1eb6b...."
    }
  ]
}
```

To manage searches or export data using searches for a company other than your **default company** you will use the ID of the appropriate company.

## Specifying the target company for earned media features

### Fetching searches of another company

By default when you fetch searches from the API you will receive the searches belonging to your **default company**.

If however you provide the `company_id` parameter with the ID of another company you have access to, you will receive the searches for that company. (See the [endpoints specification](/api-reference/api-reference-overview) for details.)

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches?company_id=61d07a1eb6b..." \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

You can then use these searches to run an export.

### Exporting earned media using a search from another company

By default when you create an export using the API you can use a search from your **default company**.

If however you provide the `company_id` parameter with the ID of another company you have access to, you can run an export using a saved search for that company. (See the [endpoints specification](/api-reference/api-reference-overview) for details.)

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/exports/one-time?company_id=61d07a1eb6b..." \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data "{
  \"onetime_export\": {
    \"search_ids\": [<search_id>],
    \"start_date\": \"2018-09-01T01:00:00\",
    \"end_date\": \"2018-10-01T01:00:00\"
  }
}"
```

The export itself will be owned by the **default company** and package limits will be applied for this company, however the saved search details will be accessed from the other company.

### Analyzing earned media using a search from another company

By default when you run analytics using the API you can use a search from your **default company**.

If however you provide the `company_id` parameter with the ID of another company you have access to, you can run analytics using a saved search for that company. (See the [endpoints specification](/api-reference/api-reference-overview) for details.)

### Streaming earned media using a search from another company

By default when you create a data stream using the API you can use a search from your **default company**.

If however you provide the `company_id` parameter with the ID of another company you have access to, you can run a data stream using a saved search for that company. (See the [endpoints specification](/api-reference/api-reference-overview) for details.)

### Managing searches for another company

Managing searches and source selections for a specific (ie non-default) company is simple. Most of the search / source selection endpoints accept an optional query parameter named `company_id`. If this parameter is specified the request will be made for that particular company (otherwise, it will fall back to your default company). See the [endpoints specification](/api-reference/api-reference-overview) for details.

## Specifying the target company for owned social features

By default when you call owned social endpoints the API will try to access accounts connected to your **default company**.

If however you provide the `company_id` parameter with the ID of another company you have access to, the API will be able to access social accounts connected to the company you specify.

---

## Overview(Getting-started)


Welcome to the Meltwater API. This guide will help you get started with the API features.

## Subscribe to API status updates

Before you go any further, please make sure you subscribe to updates from our Status Page.

We aim for a very high uptime for our platform, but inevitably incidents can happen. The status page is the best way to stay informed.

## Create your API token

When you call the API you will need to provide an API token. You can create an API token in the Meltwater application.

Read the [API Credentials](/guides/getting-started/api-credentials) page to learn more.

## Get started with API features

The API offers a number of top-level features. For each feature take a look at the overview page which links to guides on how to get started.

<ProductCards>
  <ProductCard
    title="Listening"
    description="Search, stream and export mentions from billions of editorial and social sources — with analytics, filters, and real-time delivery."
    icon="/assets/images/home/listening.png"
    darkIcon="/assets/images/home/listening.dark.png"
    to="/guides/listening/overview"
  />
  <ProductCard
    title="Mira API"
    description="Generate AI-powered summaries, insights and analysis from news and social data — and embed them directly into your own tools."
    icon="/assets/images/home/mira_api.png"
    darkIcon="/assets/images/home/mira_api.dark.png"
    to="/guides/mira-api/overview"
  />
  <ProductCard
    title="Social Analytics"
    description="Retrieve posts and performance metrics for your owned social accounts — engagement, reach, follower growth and more."
    icon="/assets/images/home/social_analytics.png"
    darkIcon="/assets/images/home/social_analytics.dark.png"
    to="/guides/social-analytics/overview"
  />
  <ProductCard
    title="Explore+"
    description="Access content and analytics from your private Explore+ instance — search mentions, run analytics, and manage custom fields via API."
    icon="/assets/images/home/explore_plus.png"
    darkIcon="/assets/images/home/explore_plus.dark.png"
    to="/guides/explore-plus/overview"
  />
  <ProductCard
    title="Bring Your Own Content"
    description="Ingest your own articles and data into Meltwater, then monitor, tag and analyse it alongside native editorial and social content."
    icon="/assets/images/home/byod.png"
    darkIcon="/assets/images/home/byod.dark.png"
    to="/guides/bring-your-own-content/overview"
  />
  <ProductCard
    title="Integrations"
    description="Connect Meltwater analytics to Power BI, Looker Studio, Domo and other BI tools your team already uses."
    icon="/assets/images/home/integrations.png"
    darkIcon="/assets/images/home/integrations.dark.png"
    to="/guides/integrations/overview"
  />
</ProductCards>

## Learn about limits and your usage

Which API features you can access, and your usage limits for these features will depend on your Meltwater package.

The [Usage Limits](/guides/getting-started/usage-limits) page explains how API limits are applied. If you are unsure about your limits please reach out to the support team or your account manager.

The [Accessing Usage Statistics](/guides/getting-started/accessing-usage-statistics) page explains how you can access statistics on your API usage, both through the API programmatically and in the Meltwater application.

## Getting help

If you have any questions please take a look at the [FAQs](/help/faqs) page. If you need further help please reach out to our [Support team](/help/support).

---

## Usage Limits


This page explains the limits you are subject to when using the API, including use of the tools on the developer portal (such as the Export Console, Analytics Console and Search Console).

## API Packaging

Your API limits are set by your Meltwater contract. Most core Meltwater packages now include an inclusive API allowance. To increase limits beyond the inclusive allowances, you will need a **Meltwater Insights API** package.

The following core Meltwater packages include the inclusive API allowance; MI Advanced, Social Essentials, Social Advanced, Essentials Suite and Advanced Suite.

*Note that API pricing and limits have changed over time - it is best to check your contract, with your account manager, or with support if you are unsure of your limits.*

## Listening (Earned Media)

### Historic access

Customers with **inclusive API access** have access to 12 months of historical data.

Customers with **an API package**:
 - Either your contract will specify your historical access limit (for example 12 months)
 - Or, if no limit is specified in your contract you can access the entire historic archive of news and social data.

*As an example if you are limited to 12 months of historical archive access you can export data and run analytics on data from up to 12 months back from the current date.*

### Documents per month

Customers with **inclusive API access** can export up to 30,000 documents per month.

Customers with **an API package** have their limit stated in their contract, for example 100,000 documents per month.

This limit is shared across listening features, including exports, searches and data streams, as well as Explore+ searches.

This limit is reset on the **1st day of each month**.

When you get close to your monthly limit (90% of your quota) and when you reach your limit the system will send administrators on your account an 'API Usage' system alert. See the [System Alerts](https://community.meltwater.com/alerts-205/getting-started-with-alerts-8058) help guide for more information on how to configure alert delivery.

*Note that if you export the same document twice, this will be counted as two documents. Documents are not de-duplicated.*

*You can see the number of documents you have taken from the platform by calling the `GET usage/me/metrics` endpoint. See our guide on [accessing usage statistics](/guides/getting-started/accessing-usage-statistics) for more details.*

Documents can be imported into the Meltwater Platform via [Bring Your Own Content (BYOC)](/guides/bring-your-own-content/overview). Retrieval of these imported documents through exports, searches or data streams are not counted towards your document usage limits.

### Exports

#### Exports per month

Customers with **inclusive API access** can run up to 50 exports per month.

Customers with **an API package** have their limit stated in their contract, for example 100 exports per month.

This limit is reset on the **1st day of each month**.

When you get close to your monthly limit (90% of your quota) and when you reach your limit the system will send administrators on your account an 'API Usage' system alert. See the [System Alerts](https://community.meltwater.com/alerts-205/getting-started-with-alerts-8058) help guide for more information on how to configure alert delivery.

*You can see the number of exports you have run by calling the `GET usage/me/metrics` endpoint. See our guide on [accessing usage statistics](/guides/getting-started/accessing-usage-statistics) for more details.*

:::info Understanding exports
It is important to understand that when you create an export through the Export Console or using the API this can contain up to 5 saved searches or tags. An export counts as one export against your monthly allowance, regardless of how many searches or tags it contains (up to the maximum of 5).
:::

#### Documents per export

A single export can contain a maximum of 2,000,000 documents. When an export is created, we check the number of results the export will generate. If the export is forecast to return more than 2,000,000 documents the export will be automatically sampled down to approximately 2,000,000 documents. Sampling is random across the export time window.

#### Maximum export window

Unless stated otherwise in your contract, the maximum time window for an analytics request is 12 months. For example from 1st January 2025 to 1st January 2026.

#### Endpoint limits

The following export endpoints are limited to 20 calls / minute:

* POST /export/v1/exports/one-time
* POST /export/v1/exports/recurring
* POST /v3/exports/one-time
* POST /v3/exports/recurring

### Analytics & search

*The recently added [earned media search feature](/guides/listening/searching-mentions) is limited in the same way as earned media analytics features. Calls to the search feature are counted towards your daily analytics call limit, and the same time period limits are applied.*

#### Daily calls

Customers with **inclusive API access** can run up to 50 calls per day.

Customers with **an API package** have their limit stated in their contract, for example 100 calls per day.

You can see the number of analytics calls you have requested by calling the `GET usage/me/requests` endpoint. See our guide on [accessing usage statistics](/guides/getting-started/accessing-usage-statistics) for more details.

Additionally you can inspect headers returned by the API. These headers are returned for every analytics request:

| Header Name | Description |
|-------------|-------------|
| RateLimit-Day-Limit | This is the number API credits you have per day as set by your API package. (For example 120 credits per day.) |
| RateLimit-Day-Remaining | The remaining number of API calls before you are rate limited. If this falls to 0, you are rate limited. If you hit your API limit, all subsequent requests will fail with a suitable error message and HTTP response code of 403 or 429.|
| RateLimit-Day-Reset | Unix timestamp when the next reset will occur. |

The day rate limit for a period begins when the first API request is sent after it has been reset to 0.

For example, a day rate limit period would start if the first API request is sent at 9:30am and finish 24 hours later when it is reset to 0 again. This is in contrast to the time periods for the usage statistics where the request counts for **Last 7/30 days** would consistently start at 12:00am UTC.

#### Maximum time window

Unless stated otherwise in your contract, the maximum time window for an analytics request is 12 months. For example from 1st January 2025 to 1st January 2026.

#### API call limits

In addition to the daily analytics call limit of your package, all calls to earned media analytics endpoints are limited to 5 calls / second and 100 calls / minute.

### Data Streams

#### Concurrent data streams

If you have access to the data streaming feature, your contract will state how many "Data Streams" you can run concurrently streaming data from the platform.

For example, if your contract says you can use 25 Data Streams, you can have up to 25 streams running from the API simultaneously.

You can see how many streams you have running by calling the `GET /v3/hooks` endpoint.

#### API call limits

The following export endpoints are limited to 20 calls / minute:

* `POST /v3/hooks`

## Explore+

The following endpoints are limited to 10 calls / minute:

* `POST /v3/explore_plus/analytics/custom`
* `POST /v3/explore_plus/search`

You can check the headers returned by the API to see how many calls you have remaining before you are rate limited. These headers are returned for every call to the above endpoints.

| Header Name                | Description                                                                                                                                                                                                                                                  |
|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| RateLimit-Minute-Limit     | The maximum number of API requests allowed per minute.                                                                                                                                                                                                       |
| RateLimit-Minute-Remaining | The remaining number of API calls available in the current window after the current request. If this falls to 0, you have no remaining calls in the current window, and further requests will fail with a suitable error message and HTTP response code of 429 until the limit resets. |
| RateLimit-Minute-Reset     | Unix timestamp when the next reset will occur.                                                                                                                                                                                                               |

All other endpoints are subject to the general rate limits described below.

## Mira API

If you have access to the Mira API, please note these limits.

#### Prompt executions per month

Your package will specify the number of prompts you can execute per calendar month, for example `5,000`.

### Rate limits

The Mira API is limited to **60 requests per minute**. This limit is shared across both the [Responses endpoint](/guides/mira-api/responses) and the [MCP server](/guides/mira-api/mcp-server).

### Conversation size

Conversations with Mira can contain up to **290,000 tokens** of message history. This includes all messages in the thread—both your prompts and Mira's responses. If a conversation exceeds this limit, the most recent messages are retained. See the [Mira API Responses documentation](/guides/mira-api/responses) for more details.

## General API call limits

Calls to endpoints, unless discussed above, are limited to 100 calls / minute.

Additionally, there is a global platform-wide rate limit of 2000 requests per hour per IP address. This limit exists solely for platform protection and is set high enough that normal API usage should never trigger it, regardless of your company_id.

*You can see the number of API calls you have requested by calling the `GET usage/me/requests` endpoint. See our guide on [accessing usage statistics](/guides/getting-started/accessing-usage-statistics) for more details.*

---

## Domo

# Importing data into Domo

Domo offers a connector for the Meltwater API that allows you to bring results of earned media exports and analytics into their platform.

You can read about the connector on the [Domo knowledge base](https://domohelp.domo.com/hc/en-us/articles/360057028474-Meltwater-Connector). You can also read Domo's overview on [using connectors](https://domohelp.domo.com/hc/en-us/articles/360042926274-Adding-a-DataSet-Using-a-Data-Connector).

In this guide we'll walk through the process of using the connector to bring export and analysis results into Domo.

## Before you start

* Make sure you have an `ACTIVE` (reoccurring export) or `FINISHED` (one-time export) export.
* Make sure you have access to a Domo account. If you don't yet have a Domo account they offer a [free sandbox environment](https://developer.domo.com/docs/developer-sandbox/sign-up) which you can use to try the Meltwater connector.

## Accessing the Meltwater connector

Once you have signed into Domo, starting from your dashboard:

* Select **DATA** in the toolbar at the top of the screen.
* Under **CONNECT DATA** at the top of the page select **Cloud App**.
* Search the available connectors for "Meltwater".
* Click on the Meltwater connector.
* Click **GET THE DATA** to start configuring the connector.

## Providing your Meltwater API credentials

The first step of using the connector is to provide your Meltwater API credentials.

Enter your API token (key) and click **Next** to continue.

## Choosing data to import

The next step is to configure the connector to fetch the data you'd like to import.

You can choose to import one of:

* The result of a `One Time Export`
* The result of a `Recurring Export`
* The result of an analysis request

The connector only allows you to select one data set for import. You can import multiple exports or analysis results by creating multiple connections.

*Note that not all customers have access to exports and analytics features. If you are unsure check with your account manager or the support team.*

### Importing an earned media export

To import an export result:

* Select `One Time Export` or `Recurring Export` as the `REPORT` type.
* For `COMPANY` most customers will only have one company listed, this is their Meltwater account. If you have access to multiple Meltwater accounts / companies you can select the appropriate company here.
* Select the `EXPORT` you'd like to import. In the list exports are identified by their ID and the name of the first search / tag in the export configuration.

The connector imports the majority of data fields for an export, but if you'd like to import authors, key phrases, matched keywords, or tags you need to select one of these using the `ADDITIONAL DATA` field. (Currently the connector does not support importing all of these fields in one connection.)

Click **Next** to continue.

### Importing an earned media analysis

To import an analysis result:

* Select the appropriate analysis type from the `REPORT` dropdown. For example to import a 'top keyphrases' analysis select "Analytics Top Keyphrases".
* For `COMPANY` most customers will only have one company listed, this is their Meltwater account. If you have access to multiple Meltwater accounts / companies you can select the appropriate company here.
* Select a `SAVED SEARCH` for your analysis. Only one search is allowed.
* Select a `SOURCE` for the analysis, for example "Twitter".
* Depending on the analysis type you have chosen there may be additional options, such as `LEVEL` for top locations analysis.
* Select a `DATE SELECTION` for the analysis. We recommend you choose `Date range` here as it is easiest to relate to the API.

The above parameters request a 'top keyphrases' analysis for the chosen search, for the selected source over the last 7 days.

Click **Next** to continue.

## Setting a data refresh schedule

The connector can pull fresh data on a schedule.

### One-time exports

If you are importing a one-time export you don't want to refresh the data on a schedule, so set the `Update interval` to `Manually`.

### Recurring exports

If you are importing a recurring export you can set the connector to refresh on a schedule that matches the schedule for the API export.

For example if you have an export scheduled to run weekly, you can set up the Domo connector to run once the API export is complete. We recommend you allow 30 minutes for the API export to complete before attempting to fetch data using the Domo connector.

### Analysis requests

For analysis requests you can set a schedule that is appropriate for the analysis configuration. For example, if your analysis requests top keyphrases for the last week you might set a schedule to pull a refreshed analysis each week on a Monday.

Whether or not you set a schedule you can choose one of two UPDATE METHODs. Choose `Replace` to completely replace the data set each time data is refreshed, choose `Append` if you'd like to keep all data and just add additional data to the set each time.

Click **Next** to continue.

## Naming your dataset

Finally you need to give a name to your dataset. You can optionally add a description too.

Enter a name and click **Save** to continue.

Once you click Save the connector will bring data in to Domo for use in your analysis project.

## How the connector consumes your API limits

For exports, the connector itself will not consume your API limits. For one-time exports your limits are consumed when you create the export using the Export Console or by calling the API. For recurring exports your limits are consumed each time the export is run on your chosen schedule by the API. Refreshing the data for an export in Domo simply downloads the existing export result.

For analytics, the connector will call the appropriate analytics endpoint. Therefore when you first fetch data through the connector, or the connector refreshes the data, each time this will use one of your analysis calls from your limit.

---

## Generic Integration

# Importing CSV/JSON data into other tools

There are a wide range of marketing, BI, analytics, dashboarding and CRM tools on the market. Many of these tools have the ability to import data in CSV and/or JSON format. In this guide we cover how to access results of earned media exports in CSV/JSON format from the API, then bring these into an example external tool.

For our examples we have chosen [Zoho Analytics](https://www.zoho.com/). Of course the exact process varies between tools, but hopefully this guide helps you get started with your chosen tool.

## Before you start

To complete this guide you will need:

* Access to a tool that understands CSV/JSON data.
* An `ACTIVE` (recurring) or `FINISHED` (one-time) export.

## Importing export results as a CSV

Start by navigating to the Export Console and sign in with your Meltwater credentials.

In the export console you will see your exports listed. In the Data column for each finished or active export you'll see two links; one for the data in CSV format, the other for JSON format.

Some tools are able to read CSV data from a web address, others will ask you to upload a file.

If your tool cannot read from a web address you can click on the CSV link and the file will be downloaded, which you can upload to your tool.

Zoho Analytics can read from a web address, so we need to copy the URL for the CSV file, ready to paste into Zoho. Right-clicking on the 'CSV' link allows us to copy the URL.

In Zoho we can then create a new data table, pasting in the URL we just copied in the URL field.

Zoho will parse the CSV data into a table that can be used to build reports.

## Importing export results as a JSON

Importing export results using JSON is a very similar process to the steps above.

If your tool cannot read JSON from a web address you will need to open the JSON link from the Export Console for your chosen export, then save this from your browser, ready to upload to your tool.

If your tool does read JSON from a web address (like Zoho), you will need to right-click the JSON link in the Export Console and copy the link address.

In Zoho we can then create a new data table, pasting in the URL we just copied in the URL field.

In general most tools do a good job of reading CSV data, but this is less true for JSON because of the nested format. It's hard for tools to have a generic approach. You may need to take steps to tidy up the data once it is imported.

In this case Zoho does a good job of reading the JSON data, but because of the number of fields, the resulting table has many columns. Therefore once the table was created the next step was to remove columns that weren't needed.

You may find that your tool asks you for a path to start from in the JSON structure, or to choose certain portions to import.

---

Unfortunately it is not practical for us to try and document every tool available in the market. Hopefully this guide will give you a start on bringing Meltwater data into your tool.

If you have questions about a specific tool please [contact support](/help/support) as we may have helped other customers with your tool in the past.

---

## Looker Studio

# Importing into Looker Studio

API customers can use Meltwater's Looker Studio Connector to bring earned media and owned social metrics into their dashboards. This guide explains how to get started with the connector.

*Currently the connector for Looker Studio does not support earned media content (the API export feature). There are multiple options for bringing in export results explained below.*

## Before you start

To complete this guide you will need:

* Access to [Looker Studio](https://lookerstudio.google.com/)
* Your [Meltwater API token](/guides/getting-started/api-credentials)

## Bringing in earned and owned metrics

Whether you are bringing in earned media or owned social metrics, you need to start by choosing to create a new Data Source in Looker Studio.

You will be shown the library of connectors for Looker Studio. Type "meltwater" into the search box to find the connector.

Click on the connector. We recommend that you immediately replace the default name "Untitled Data Source" with something meaningful for your project.

### Authorizing the connector

If you have not used the connector before you will be asked to authorise the connector. The connector needs to be authorised so that it can access the Meltwater API and bring data into Looker Studio for you.

Authorise the connector to continue.

### Providing your API token

Next you will need to enter your API token. You can read more about your API token on the [API Credentials page](/guides/getting-started/api-credentials).

Enter your API token and click Submit to continue.

If you use the connector again in future you will not need to do these steps again, unless you choose to revoke the connector's access.

### Choosing a company and feature for your analysis

Now that you have authenticated the connector you will be asked to configure your analysis.

Firstly select the 'company' you'd like to use. In the Meltwater platform companies own searches, this is the account name you see in the top-right of the Meltwater application.

*For most customers there will only be one company, but you may have access to different companies/accounts on the Meltwater platform (for example if you are a large company with accounts for each of your teams).*

Select your company and click Next to continue.

Next you need to choose the analysis feature you'd like to use; either **Earned media analytics** or **Owned social analytics**.

Select a feature and click Next to continue. The two features are explained in the next sections of the guide.

### Earned media analytics

*Please make sure you have at least one Saved Search in your Meltwater account before you proceed.*

If you choose the earned-media analytics feature, the configuration steps will ask you to choose a search, an analysis type and to complete additional parameters depending on the analysis type chosen.

Start by choosing the search for your analysis, and the type of analysis you'd like to perform.

*To learn more about the available analysis options — see the [Analytics Options page](/api-reference/analytics-options/listening).*

When you click Next the connector will ask you for additional parameters, appropriate to the analysis type you've asked for.

For example, if you choose the Top Locations analysis, you will be asked for a source and location level.

Select options for the parameters, then click Next to continue.

At this point you have entered all the parameters needed for the analysis and Looker Studio will tell you to click Connect to continue. When you click Connect you will be shown the schema for the analysis data, and you will be able to explore the data or bring it into your dashboard.

When you create a report or open the Explorer tool in Looker Studio, data will be fetched from the API, consuming an analysis call from your allowance.

### Owned social analytics

*Please make sure you have at least one owned social account connected to your Meltwater account.*

If you choose the owned social analytics feature, the following configuration steps will ask you to choose a social network, the social accounts to analyse and the type of analysis to perform.

Start by choosing the social network for your analysis. When you click Next you will be asked to choose the social accounts to analyse, and the analysis to perform.

*To learn more about the available analysis options — see the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page.*

Select options for the parameters, then click Next to continue.

At this point you have entered all the parameters needed for the analysis and Looker Studio will tell you to click Connect to continue. When you click Connect you will be shown the schema for the analysis data, and you will be able to explore the data or bring it into your dashboard.

### Choosing a time period for your analysis

You'll notice that so far you have not been asked for a time period for the analysis. This is because Looker Studio automatically defaults to the last 28 days for the time period.

To learn more about date range controls in Looker Studio see the [help guide](https://support.google.com/datastudio/answer/6291067).

### Refreshing data

Looker Studio will automatically refresh the data for your analysis request every 12 hours. Note that this will consume calls from your API analytics allowance.

## Options for bringing in earned-media export results

### Before you start

Make sure you have an `ACTIVE` (recurring) or `FINISHED` (one-time) export available in the API.

### Creating a new Data Source

To use export results in Looker Studio you will need to create a Data Source. At this point you will be asked to choose a connector for your data source. There are a number of options you can choose.

### Google Sheets connector

One option is the Google Sheets connector. This connector allows you to choose a Google Sheets document in your Google Drive as a source of data. Using the `IMPORTDATA` function in Google Sheets you can bring in the results of an API export, then use the Google Sheets connector to bring the data in to Looker Studio. Using this method the data will be refreshed automatically for you.

#### Copy the CSV link for your export

Start by navigating to the Export Console and sign in with your Meltwater credentials.

Right-click the 'CSV' link for the export and copy the URL. You'll need this in the next step.

#### Import export data into a Google Sheet

Create a new Google Sheet in Google Drive. This sheet will hold the data from the API before it is imported into Looker Studio.

In cell `A1` of the new sheet, enter the following formula:

`=IMPORTDATA("<LINK TO CSV COPIED IN LAST STEP>", "\t")`

Note that in this formula you are:

* Giving the URL for your exported data in CSV format
* Specifying that the delimiter for the data is a tab

Google Sheets will now import the data and will create columns based upon the headers in the CSV data.

#### Configure a new Google Sheets data source

In Looker Studio create a new data source, using the Google Sheets connector. Select the spreadsheet you created in the previous step, and the worksheet where the data is held.

Once you click **CONNECT** data from the spreadsheet will be imported into Looker Studio for your analysis.

#### Refreshing data

If you are running a recurring export and want data to be refreshed in Looker Studio, this method will automatically refresh the data for you.

The `IMPORTDATA` function in Google Sheets will automatically check the URL you gave for the API export every hour. If there is new data this will be imported for you.

The Google Sheets connector will also refresh data every hour by default.

Therefore without any changes following the steps above will refresh your export data in Looker Studio.

### CSV Upload connector

Another option is the File Upload connector. This connector allows you to select a CSV file for upload.

*Note that this connector is very sensitive to encodings and formats. It currently only accepts UTF-8 encoded files delimited using commas.*

The CSV files output by the Meltwater API are not in the exact format this connector requires. This means you will need to:

1. Download the CSV result of the API export.
2. Open the file in Excel, Numbers or a similar spreadsheet application.
3. Export the file as CSV in UTF-8 format.

You can now upload the UTF-8 CSV file using the File Upload connector.

Once you click **CONNECT** data from the file will be imported into Looker Studio for your analysis.

### Supermetrics Custom JSON/CSV/XML connector

Supermetrics offer a connector that allows you to ingest CSV or JSON data from a URL.

*Note that Supermetrics charge for use of this connector. You can try the connector through a free 14-day trial.*

This connector is described in more detail in the [Supermetrics documentation](https://support.supermetrics.com/support/solutions/articles/19000106390-how-to-connect-json-csv-xml-data-from-an-api).

In the options provided by the connector you will need to specify:

* For `Source URL` the URL for the JSON formatted API export (you can find this from the Export Console).
* For `JSONPath` you can specify where the data records can be found in the JSON data. For Meltwater API exports the path is `data`.
* Tick `Convert numeric-looking values to numbers` and `Convert date-looking values to dates` so that numbers and dates are imported in the correct format.

Once you click **CONNECT** data from the file will be imported into Looker Studio for your analysis.

---

## Overview(Integrations)

# Integrations

The following guides explain how you can import results from the Meltwater API into tools such as BI applications.

| Integration | Description |
|-------------|-------------|
| [Power BI Desktop](/guides/integrations/power-bi) | How to import data from the API into Microsoft Power BI Desktop using the Meltwater connector |
| [Power BI Service](/guides/integrations/power-bi-service) | How to build automatically refreshing reports in Power BI Service |
| [Tableau](/guides/integrations/tableau) | How to bring exports and analytics into Tableau Desktop (connector is now deprecated) |
| [Looker Studio](/guides/integrations/looker-studio) | How to import data from the API into Looker Studio |
| [Domo](/guides/integrations/domo) | How to import data from the API into Domo |
| [Generic CSV/JSON](/guides/integrations/generic) | How to import into tools that read CSV / JSON data |

---

## Power BI Service

# Building reports in Power BI Service

Meltwater offers a Power BI connector as described in [this guide](/guides/integrations/power-bi), however as this connector is not yet certified by Microsoft you cannot use the connector in Power BI Service. In this guide we will show you how you can use out-of-the-box Power BI features to build reports in Power BI Service.

## Before you start

To complete this guide you will need:

* [Microsoft Power BI Desktop](https://www.microsoft.com/en-us/download/details.aspx?id=58494) installed
* Access to [Power BI Service](https://app.powerbi.com)
* Your [Meltwater API token](/guides/getting-started/api-credentials)

## Overview

For most customers the need to use Power BI Service stems from wanting to have automatically refreshing reports that can be shared with stakeholders. In this guide we will assume that you would like to bring data in and refresh that data on a schedule.

Below we will cover each type of data you might want to bring into your Power BI Service reports. The approach is the same in each case:

* Use the built-in Web data source to call the Meltwater API and bring in the data
* Modify the code generated by Power BI so that the latest data is fetched for each scheduled refresh
* Build a report in Power BI Desktop
* Publish the report to Power BI Service
* Set up a schedule for refreshing the data

## Using the Web data source to fetch data

### Earned media exports

You can use the built-in Web data source to bring in the results of a recurring earned media export.

Firstly, make sure you have created your recurring export in the Export Console tool. Make sure when you create the export the refresh schedule matches your intended refresh schedule for the eventual report. For example, if you want a weekly refreshing report make sure you set the export schedule to run each week.

Next, right-click the JSON link for your recurring export and copy the URL.

In Power BI choose to create a new data source, selecting the **Web** option.

Paste the URL you copied for your export result into the settings for the Web data source and click **OK**.

Power BI will load the data from the URL and automatically detect the schema and data types for the data.

Generally Power BI does a good job of detecting the types for each data field, but it's worth checking at this point that the types suit your analysis.

*Unfortunately you will not be able to expand fields like keywords and key phrases alongside the document fields in one data source. If you do need this data, you can create another data source, expand the fields as you need, then join this second data source onto your first data source using the document ID as the join field.*

Now that you have imported the data you can create a visualisation and start building a report.

For earned media exports you do not need to modify the code generated by Power BI to bring in fresh data for each refresh. This is because the API overwrites results for each export run to the same URL. You can go straight to [Publishing to Power BI Service](#publishing-to-power-bi-service) to continue.

### Earned media analytics

You can use the built-in Web data source to bring in the results of an earned media analytics query.

Start by using the Analytics Console tool to find the URL for your required analysis. Open the "View API request code" area to see the request details and copy the URL for the request.

In Power BI choose to create a new data source, selecting the **Web** option.

Choose **Advanced** in the Web data source dialog, then paste in the URL you copied above. Also add a HTTP header called `apikey` and for the value insert your Meltwater API key.

When you click **OK** Power BI will call the API and fetch data for the analysis. It will take you to the Power Query Editor to see the results.

Generally Power BI does a good job of detecting the types for each data field, but it's worth checking at this point that the types suit your analysis.

Now that you have imported the data you can create a visualisation and start building a report.

As it stands, if you refresh the data the connector will fetch the analysis for the same time window as you selected in the Analytics Console. The steps in [Modifying queries to fetch the latest data](#modifying-queries-to-fetch-the-latest-data) below explain how to modify the code generated by Power BI to fetch the latest data for each refresh.

### Owned social analytics

You can use the built-in Web data source to bring in the results of an owned social analytics query.

Unlike earned media analytics we do not currently provide a tool that helps build the URL for these queries. Please refer to the [developer documentation](/guides/social-analytics/overview) for details on how to construct a URL for a request.

As an example, the following URL would access a number of account-level metrics for a Facebook account:

`https://api.meltwater.com/v3/owned/accounts/metrics/numeric?source=facebook&account_ids=[ACCOUNT ID]&start=2021-12-06&end=2021-12-12&metrics=page_fans,page_impressions,page_video_views`

In Power BI choose to create a new data source, selecting the **Web** option.

Choose **Advanced** in the Web data source dialog, then paste in the URL for your request. Also add a HTTP header called `apikey` and for the value insert your Meltwater API key.

When you click **OK** Power BI will call the API and fetch data for the analysis. It will take you to the Power Query Editor to see the results.

Now that you have imported the data you can create a visualisation and start building a report.

As it stands, if you refresh the data the connector will fetch the analysis for the same time window as this is hard-coded in the URL. The steps in [Modifying queries to fetch the latest data](#modifying-queries-to-fetch-the-latest-data) below explain how to modify the code generated by Power BI to fetch the latest data for each refresh.

## Modifying queries to fetch the latest data

For earned media analytics and owned social analytics, to have the data source fetch the latest data on each refresh you will need to modify the code generated by Power BI.

Open your query for editing in the Power Query Editor. Click on the **Advanced Editor** button in the Home ribbon menu to see the code Power BI has automatically generated.

### Create a reusable time window function

The first step is to create a reusable function that will help select a time window based on your current date and time.

Close the **Advanced Editor** window, to return to the main window. Then, from the Home ribbon menu select **New Source** then **Blank Query**.

Once the query has been created click on **Advanced Editor** in the Home menu ribbon.

For earned analytics, replace the existing code with the following:

```
(period_days as number, optional period_time as time) =>
let
    _period_time = if period_time = null then #time(0,0,0) else period_time,
    end = Date.StartOfDay(DateTimeZone.LocalNow()) + #duration(0, Time.Hour(_period_time), Time.Minute(_period_time), Time.Second(_period_time)),
    start = Date.AddDays(end, -period_days)
in
    [ start = DateTimeZone.ToText(start, "yyyy-MM-ddTHH:mm:ss"), end = DateTimeZone.ToText(end, "yyyy-MM-ddTHH:mm:ss")]
```

For owned analytics, replace the code with:

```
(period_days as number, optional period_time as time) =>
let
    _period_time = if period_time = null then #time(0,0,0) else period_time,
    end = Date.StartOfDay(DateTimeZone.LocalNow()) + #duration(0, Time.Hour(_period_time), Time.Minute(_period_time), Time.Second(_period_time)),
    start = Date.AddDays(end, -period_days)
in
    [ start = DateTimeZone.ToText(start, "yyyy-MM-dd"), end = DateTimeZone.ToText(end, "yyyy-MM-dd")]
```

*These functions return a start and end date-time, based upon the parameters you provide and your current date and time. For example, if you provide `7` for the `period_days` parameter, it will return a start and end date-time which cover the last 7 days, ending at 00:00 of your current day. It also supports an optional `period_time` parameter which allows you to set a specific time rather than 00:00.*

The two functions above are the same, except that the earned analytics endpoints require date & time for start and end parameters, whereas owned endpoints only require dates.

Click **Done**, then right-click on the query in the left-hand panel and choose to **Rename** the query as `RelativeTimeWindowParameters`.

### Modify the Power BI code to use the time window function

Staying within the Power Query Editor window select your query that calls the API in the left-hand panel.

Click on the **Advanced Editor** button in the Home ribbon menu to see the code Power BI has automatically generated for the query.

Modify the code as follows:

* Under `let` create a new line calling your new function, saving the result as a variable called `time_window_params`. The parameter for the function is the size of your time window in days.

    `time_window_params = RelativeTimeWindowParameters(7),`

* On the next line you need to create a set of parameters you will pass to the API. This is the query string parameters from the URL you originally entered without the `start` and `end` parameters, combined with the result from the function above.

    `params = Record.Combine({ time_window_params, [company_id="5e303eb8d4b0100010239ffc", source="news", size="200", tz="Europe/London"] }),`

* Finally, modify the line beginning `Source = ...`. Change the first argument for the Web.Contents function to just `https://api.meltwater.com`, moving the rest of the URL minus the query string to the `RelativePath` parameter. Then add a `Query` parameter to the `Web.Contents` call, giving the `params` variable from above as the value.

    `Source = Json.Document(Web.Contents("https://api.meltwater.com", [RelativePath="/v3/analytics/17967704/top_keyphrases", Headers=[#"apikey" = "a0191e7be2e35940f1aa826ac73b1e76"], Query=params])),`

Click **Done** to close the dialog, and test your changes by refreshing your data.

*Technical note: The first param of Web.Contents function must be static, otherwise Power BI thinks it's a 'dynamic data source' and refuses to refresh it in Power BI Service. This is why we suggest modifying the code as described to avoid this issue.*

## Publishing to Power BI Service

Once you have built your report you can publish this to Power BI Service.

In the Home ribbon menu, click **Publish** to start the process.

Power BI will ask you to choose a workspace to publish to. Wait for the publish process to complete, then check that your report has been published successfully.

## Set up refresh schedule

Now that you have published your report the next step is to set up a schedule that will refresh the data.

When Power BI publishes your report it will automatically create a Dataset in Power BI service. You can view your data sets by clicking on **DataSets** in the left hand menu of the Power BI Service application.

Find the data source for your report, click on the data source to access the data source settings, then click on **Schedule refresh** in the **Refresh** menu.

Scroll down to the **Scheduled refresh** settings and expand this area if it is not already shown.

### Earned media exports

In the settings area you can set a refresh schedule that matches your schedule for your recurring earned media export.

As it can take up to 30 minutes for an earned media export to run, we recommend you set a refresh schedule in Power BI Service that allows for the export to finish. For example, in this case we set the schedule to refresh 1 hour after the export itself is scheduled.

**Apply** the settings and you are all set. Power BI Service will now refresh your data automatically and your report will show the latest data after each refresh.

### Earned media and owned social analytics

In the settings area you can set a refresh schedule that matches your reporting need. For instance, if you would like the data to refresh each day you can create a schedule for this, such as scheduling a refresh every day at midnight.

Note that when you set up a schedule for analytics, Power BI Service may say your data source credentials are invalid or incomplete, even though you have included a valid API key in your code.

*This happens because Power BI Service tried to validate your credentials by calling `https://api.meltwater.com` without a path to an analysis, which is not permitted by the API as it is not a valid API route.*

You can solve this by telling Power BI Service to skip its credential test. In the data source settings area, find the **Data source credentials** section, and expand this. Click on the **Edit credentials** link to edit credential settings for the data source.

Tick **Skip test connection**, and click **Sign in** to save this change. Power BI Service should now be able to refresh your data.

---

## Power BI

# Importing data into Power BI Desktop

API customers can use Meltwater's Power BI Connector to bring earned media content and metrics, plus owned social metrics into their workbooks. This guide explains how to get started with the connector.

Because this connector is not yet certified by Microsoft, please note:

- This connector is not currently listed in Power BI as a data source. You will need to install the connector yourself as described below.
- The connector works well for reports in **Power BI Desktop**, but not for **Power BI Service**. Please read the separate guide for [Power BI Service](/guides/integrations/power-bi-service).

## Before you start

To complete this guide you will need:

* [Meltwater Power BI connector file](/assets/MWPowerBIConnector_1_4_3.mez) - currently version 1.4.3
* [Microsoft Power BI Desktop](https://www.microsoft.com/en-us/download/details.aspx?id=58494) installed
* Your [Meltwater API token](/guides/getting-started/api-credentials)

## Installing the Meltwater connector

In Power BI terminology the Meltwater integration is called a 'Custom Connector'. You can read more about custom connectors [here](https://learn.microsoft.com/en-us/power-bi/connect-data/desktop-connector-extensibility).

Because the integration is a custom connector, this means you need to copy the connector file to the right location on your computer, and you must allow Power BI to use custom connectors.

The connector file will have a name in the form `MWPowerBIConnector_[version].mez`. Copy the MEZ file to `[Documents]\Power BI Desktop\Custom Connectors` (you will need to create this folder if it does not exist).

You now need to allow Power BI to use this custom connector. In Power BI, under the **File** menu select **Options and settings**, then **Options**. Go to **Security**, then allow extensions not validated by Microsoft.

Once the connector is installed, when you open the Get Data dialog in Power BI and search for "Meltwater" you will see the 'functions' you can use to access data.

## Earned media exports

This section covers how you can import the results of a "one-time" or "recurring" earned media export into Power BI.

*Please make sure you have an `ACTIVE` recurring export or `FINISHED` one-time export in `JSON` format before you proceed.*

### Selecting an export

Start by selecting the "Meltwater - Earned Media Exports" function and clicking CONNECT.

At this point you will be asked to enter your Meltwater API token. Enter your API token and click **Connect** to continue.

Next you will be shown the navigator window where you choose the export to bring in.

Expand the appropriate folder for the export type you'd like to access, then expand the export you'd like to import.

Tick the Documents table and click **Load** to continue.

Your data will be imported into Power BI. Depending on the size of the export this might take a little while.

### Creating a visualisation

You are now ready to build a report using the imported data. As a simple example you could build a donut chart showing a breakdown of sentiment.

Select Donut Chart from the list of Visualisations. From the `Documents` table drag `enrichments.sentiment` on to the **Legend** box, then drag `document_id` on to the **Values** box.

This will give you a simple chart. Please consult the Power BI documentation to explore more options for your visualisations and reports.

## Earned media analytics

This section covers how you can import earned media analytics results into Power BI.

*Please make sure you have at least one Saved Search in your Meltwater account before you proceed.*

### Selecting an analysis type

Start by selecting the "Meltwater - Earned Media Analytics" function and clicking CONNECT.

Start by choosing the analysis you'd like to perform.

*To learn more about the available analysis options — see the [Analytics Options page](/api-reference/analytics-options/listening).*

### Choosing a time period

Next you need to specify a time period for your analysis. The connector allows you to choose either a relative or absolute time period.

*Note that the connector uses the local time zone of where you are running Power BI when calling the API.*

To specify a relative time period, use the following parameters:

- **Relative time period: Number of days** — Enter the size of the required time period in days. For example `7` would be the last 7 days.
- **Relative time period: Time** — Optionally use this parameter to override the time of day for the time period.

To specify an absolute time period, use the following parameters:

- **Absolute time period: Start** — The start of the time period to analyse.
- **Absolute time period: End** — The end of the time period to analyse.

Enter a relative or absolute time period, then click **OK** to continue.

### Entering your API token

At this point you will be asked to enter your Meltwater API token. Enter your API token and click **Connect** to continue.

### Choosing a company, search and source

Finally Power BI will show you a navigator window for your analysis request where you will need to choose the company, search and source for your analysis.

The top level of the navigator tree represents the "companies" you have access to through your Meltwater account. For most customers there will only be one company, but you may have access to different companies/accounts on the Meltwater platform.

Expand the company you'd like to use to see a list of searches owned by that company. Next expand the folder for the search you'd like to use where you will see a list of sources you can choose from.

The "All" source option will carry out an analysis including all sources you have access to.

Click **Load** to continue. This will fetch results from the API and bring them into Power BI.

### Creating a visualisation

Now that you have imported an analysis result you can build a visualisation using the data. As a simple example, you could bring in a "Top Keyphrases" analysis result and create a tree map.

Select Treemap from the list of Visualisations. Drag the `keyphrase` field from the data schema on to the **Group** box, then drag the `document_count` field on to the **Values** box.

## Owned social analytics

This section covers how you can import owned social analytics results into Power BI.

*Please make sure you have at least one [owned social connection](https://community.meltwater.com/engage-setup-45/grouping-your-owned-social-accounts-in-meltwater-social-connections-owned-tab-7704) configured in your Meltwater account before you proceed.*

### Choosing a source

Start by selecting the "Meltwater - Owned Social Analytics" function and clicking CONNECT.

First you will need to choose the social network (source) for your analysis.

### Choosing a time period

Next you need to specify a time period for your analysis. The connector allows you to choose either a relative or absolute time period.

To specify a relative time period, use the following parameters:

- **Relative time period: Number of days** — Enter the size of the required time period in days. As an example, if you specify `7 days`, the period will be one week up until "yesterday". If you refresh your data in a week's time, the time window will automatically move to a week later.

To specify an absolute time period, use the following parameters:

- **Absolute time period: Start** — The start of the time period to analyse.
- **Absolute time period: End** — The end of the time period to analyse.

Enter a relative or absolute time period, then click **OK** to continue.

### Entering your API token

At this point you will be asked to enter your Meltwater API token. Enter your API token and click **Connect** to continue.

### Choosing a company, account and analysis type

Finally Power BI will show you a navigator window for your analysis request where you will need to choose the company, account and analysis type.

Expand the company you'd like to use to see a list of owned social accounts connected for that company, then expand an account to see a list of analysis types you can choose from.

Select the company, account and analysis type you'd like to use then click **Load** to continue. This will fetch results from the API and bring them into Power BI.

### Supported analysis types

The analysis types you can choose from will depend on the social network for an account.

For more information see the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page.

## Refreshing data

In Power BI you can refresh the data in your report by clicking the Refresh button in the Home ribbon.

For earned media exports this will re-fetch data for the export from the API. For a one-time export this will have no value, but if you imported a recurring export, you can refresh your data in Power BI after the export is updated to bring in the latest results.

For earned media analytics this will re-fetch the analysis results from the API. If you specified a relative time window (for example the last 7 days), this will update the analysis results appropriately.

For owned social analytics this will re-fetch the analysis results from the API. If you specified a relative time window, this will update the analysis results appropriately.

## Consumption of API limits

For earned media exports the connector itself will not consume your API limits. For one-time exports your limits are consumed when you create the export using the Export Console or by calling the API. For recurring exports your limits are consumed each time the export is run on your chosen schedule by the API. Refreshing the data for an export simply downloads the existing export result.

For earned media analytics the connector will call the appropriate analytics endpoint. Therefore when you first fetch data through the connector, or the connector refreshes the data, each time this will use one of your analysis calls from your limit.

For owned social analytics features we do not set package limits on the API. All customers are subject to fair-usage limits, but as these are high limits for most use cases you shouldn't encounter any issues.

## Clearing saved API tokens

When you use any of the features described above Power BI will store your API token so that you don't have to enter this frequently.

You can clear any API token stored by Power BI by going to **File > Options and settings > Data source settings**. Here you can 'clear credentials' for any connector.

---

## Tableau

# Importing data into Tableau Desktop

:::warning Connector deprecated
Our Tableau connector is now deprecated. Please contact our support team if you have questions.
:::

API customers can use Meltwater's Tableau Web Data Connector to bring earned media content and analytics into their workbooks. This guide explains how to get started with the connector.

*Note that not all customers have access to all of the API features below. If you are unsure check with your account manager or the support team.*

## Accessing the Meltwater Web Data Connector

In Tableau Desktop, under the **Data** menu select **New Data Source**.

Under the "To a Server" section select **Web Data Connector**.

This opens the Web Data Connector window. Enter `https://api.meltwater.com/connect/tableau/` in the location bar and hit return. This will load the connector wizard.

## Providing your Meltwater API credentials

The first step of using the connector is to provide your Meltwater API credentials. Enter your API token and click **Next** to continue.

Next you will be asked what data you'd like to import. Each option is covered in the following sections.

## Earned media exports

This section covers how you can import the results of a "one-time" or "recurring" earned media export into Tableau.

*Please make sure you have an `ACTIVE` recurring export or `FINISHED` one-time export before you proceed; the export must also use the JSON format.*

### Selecting an export

To import an export result, for the second wizard step select `Earned Media - One-time Export` or `Earned Media - Recurring Export`.

Click **Next** to continue, where you will be shown your list of exports which are available for import.

*In the list exports are identified by their ID and the name of the first search / tag in the export configuration.*

Select an export then click **Run** to finish the wizard and return to Tableau.

### Configuring tables in your data source

When you are returned to Tableau you will be in the Data Source editor. At this point you will need to select which of the tables provided by the connector you'd like to have in your data source.

For an earned media export you'll see the following tables:

* Documents
* Key Phrases
* Authors
* Matched Keywords
* Tags

Drag the tables you need into the top right panel. The Documents table is the main table with all the search result documents. The rest of the tables contain additional information and use `document_id` as the foreign key to relate to the Documents table. If you drag multiple tables into your data source Tableau will attempt to suggest a column to join the tables on.

If you like you can click the **Update Now** button to get a 1000 row preview of the data.

### Using imported data in a worksheet

Navigate to your Tableau worksheet. This starts the Tableau data extract creation process and imports the data into the workbook.

Once done Sheet 1 is activated you can see all available Dimensions and Measures on the Data tab on the left.

Now the data is ready to be dragged and dropped into the sheet to start creating reports.

### Refreshing your data

When you set up the connector, then first bring data into a worksheet, Tableau creates an 'extract' of the data.

If you'd like to refresh the data (for example you have imported a recurring export and want the latest data) you need to refresh the extract. Select the data source in the Data menu and choose the refresh extract option.

### Consumption of API limits

For earned media exports the connector itself will not consume your API limits. For one-time exports your limits are consumed when you create the export using the Export Console or by calling the API. For recurring exports your limits are consumed each time the export is run on your chosen schedule by the API. Refreshing the data for an export in Tableau simply downloads the existing export result.

## Earned media analytics

This section covers how you can import the results of an earned media analysis into Tableau.

*Please make sure you have at least one Saved Search in your Meltwater account before you proceed.*

### Configuring an analysis

To import an analysis result, for the second wizard step select `Earned Media - Analytics`. Click **Next** to continue.

Next you need to configure your analytics request:

* Firstly choose the saved search you'd like to use
* Next choose a start and end date for your analysis
* Now choose an analysis type, for example "Top key phrases"

The remaining options will depend on the analysis type you choose. Select options for the remaining parameters.

Click **Run** to finish the wizard and return to Tableau.

### Configuring tables in your data source

When you are returned to Tableau you will be in the Data Source editor.

Most analysis types will only return one table, which is automatically included in your data source. You can immediately start using the data in a worksheet.

The 'Summary' analysis however includes a number of tables:

* Daily timeseries
* Hourly timeseries
* Sentiment
* Summary
* Top countries
* Top languages

Drag **one** of these tables into your data source, then you will be ready to use the data in a worksheet.

### Using imported data in a worksheet

Navigate to your Tableau worksheet. This starts the Tableau data extract creation process and imports the data into the workbook.

Once done Sheet 1 is activated you can see all available Dimensions and Measures on the Data tab on the left.

Now the data is ready to be dragged and dropped into the sheet to start creating reports.

### Refreshing data

For earned media analytics refreshing the extract doesn't make sense as the API will be called with the same date range and you will get exactly the same results. You can edit your connection if you'd like to bring in analysis results for a more recent time frame.

### Consumption of API limits

For earned media analytics, the connector will call the appropriate analytics endpoint. Therefore when you first fetch data through the connector, or the connector refreshes the data, each time this will use one of your analysis calls from your limit.

## Owned social analytics

This section covers how you can import the results of an owned social analysis into Tableau.

*Please make sure you have at least one [owned social connection](https://community.meltwater.com/engage-setup-45/grouping-your-owned-social-accounts-in-meltwater-social-connections-owned-tab-7704) configured in your Meltwater account before you proceed.*

### Configuring an analysis

To import an analysis result, for the second wizard step select `Owned Social - Analytics`. Click **Next** to continue.

Firstly you will need to specify a time period, you can choose from:

- **Relative** — A period that will automatically change if you refresh your data in future. As an example, if you specify `7 days`, the period will be one week up until "yesterday". If you refresh your data in a week's time, the time window will automatically move to a week later.
- **Absolute** — A fixed start and end date for the analysis which will not change automatically.

Next you will need to choose a source, for example "Facebook".

Based upon the source you have chosen, next you will need to choose one or more social accounts. These are the accounts connected to your Meltwater account.

Finally you will need to choose an analysis type:

- **Accounts - Metrics - Numeric** — import simple numeric metrics, such as the number of fans for a Facebook page
- **Accounts - Metrics - Breakdown** — import metrics broken down by a concept, such as countries of Facebook page fans
- **Accounts - Metrics - Nested Breakdown** — import metrics broken down by multiple concepts, such as the age and gender of Facebook page fans
- **Accounts - Metrics - Heatmap** — import metrics broken down by date and hour, such as when Facebook fans are online during the day
- **Accounts - Posts - Top Posts** — import top performing posts for an account, for example sorted by engagement rate

Depending on the analysis type you choose you may be asked for additional choices.

Click **Run** to finish the wizard and return to Tableau.

### Using imported data in a worksheet

Navigate to your Tableau worksheet. This starts the Tableau data extract creation process and imports the data into the workbook.

Once done Sheet 1 is activated you can see all available Dimensions and Measures on the Data tab on the left.

Now the data is ready to be dragged and dropped into the sheet to start creating reports.

### Refreshing data

When you set up the connector, then first bring data into a worksheet, Tableau creates an 'extract' of the data.

If you have chosen a relative time window for your analysis, you might want to refresh the data in your workbook each week for example. To do so select the data source in the Data menu and choose the refresh extract option.

Note that if you have chosen an absolute (fixed) time window for your analysis, refreshing the extract will just bring back the same data, as the time window won't have changed. You can edit your connection to choose a new time window if required.

### Consumption of API limits

For owned social analytics features, we do not set package limits on the API. All customers are subject to fair-usage limits, but as these are high limits for most use cases you shouldn't encounter any issues.

## Solving proxy issues

Since our Tableau Web Data Connector is a browser application, there are certain scenarios in which you can run into [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues.

This typically comes up when customers are trying to configure automatic refreshes in Tableau Server, fetching earned media exports, and using a proxy to fetch the data from the Meltwater API.

You would likely experience this by seeing a never-ending spinner in Tableau, when you are trying to load data using our WDC through a proxy.

### Why does this happen?

When you use the connector to retrieve earned media exports, export data will be fetched from `https://exports.meltwater.com/...`.

If you use a proxy service, as the connector is hosted at `api.meltwater.com` but is requesting data from the exports domain, this can cause CORS issues.

### How to solve this?

To solve this problem, enable CORS support in your proxy by setting `Access-Control-Allow-Origin` header to allow requests from the connector's domain.

Please refer to the official [Tableau documentation for solving CORS issues](https://tableau.github.io/webdataconnector/docs/wdc_cors).

---

## Analyzing Mentions(Listening)


In this tutorial we'll get you up and running to make your first analytics calls.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* A Saved Search in your Meltwater App account

## Obtaining a Meltwater search

Analyses are created with an existing Meltwater search.

*In this tutorial we'll cover using an existing search, but you can create / edit searches using the API. See the [Managing Saved Searches](/guides/listening/managing-searches) guide for more details.*

To create an analysis you need to provide the `id` of the required search. You can use the `GET /v3/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "searches": [
    {
      "updated": "2018-01-10T14:42:10.000Z",
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}
```

## Analytics options

The API supports two types of earned analytics features:

* **Pre-defined analytics** - individual endpoints for common analytics, such as top keywords, sentiment breakdown and number of mentions
* **Custom analytics** - go beyond pre-defined analytics options by combining measures, dimension and analysis types to meet your needs

## Pre-defined analytics

You can use our endpoints for pre-defined analytics to access common analysis needs.

In this guide we'll call the analytics summary endpoint, but each analytics endpoint is called in a similar way. The full list of analytics endpoints can be found on the [Analytics Options](/api-reference/analytics-options/listening) page.

The summary analytics endpoint returns the following analytics for a search:

- Volume - The total number of documents matching our search as well as providing an average for per day and per hour.
- Sentiment - Breakdown of the sentiment i.e. positive or negative for the documents returned by the search.
- Top Countries - Breakdown of countries where the document originated.
- Top Languages - Breakdown of languages for the documents matched.
- Time Series - A detailed breakdown by day, by hour of when the documents were created.

### Analytics parameters

When calling an analytics endpoint you need to provide:

* `start` and `end` - the time period you'd like to analyze (ISO8601 timestamps, excluding timezone/offset). *Note that the analysis will be inclusive of the start time and exclusive of the end time.*
* `tz` - An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.

You can also optionally specify a number of additional filters including:

- `source` - the source(s) you'd like to analyze, for example `news` or `blogs`. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
- `language` - A primary language subtag from the IANA language tag registry, 'zh-Hant', 'zh-Hans' or 'zz'.
- `country` - The two-letter ISO 3166-1 Alpha-2 country code, or 'ZZ'.

*Note that the period you can analyze depend on your Meltwater API package. See the [Usage Limits](/guides/getting-started/usage-limits) page for more details.*

Each analytics endpoint has its own list of required fields. For a full list see the [endpoints documentation](/api-reference/api-reference-overview).

### Example Request

To fetch the summary analytics you call the `GET https://api.meltwater.com/v3/analytics/<search_id>` endpoint.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/analytics/2382415?source=news&start=2020-08-01T00:00:00&end=2020-08-09T00:00:00&tz=Europe/London" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
   "volume":{
      "document_count":27333,
      "per_day":3416,
      "per_hour":142
   },
   "sentiment":{
      "positive":{
         "document_count":4863,
         "percentage":17.79
      },
      "negative":{
         "document_count":2270,
         "percentage":8.30
      },
      "neutral":{
         "document_count":16408,
         "percentage":60.03
      },
      "unknown":{
         "document_count":3792,
         "percentage":13.87
      }
   },
   "top_countries":[
      {
         "country_code":"IN",
         "document_count":4389,
         "percentage":16.06
      },
      {
         "country_code":"JP",
         "document_count":2683,
         "percentage":9.82
      }
   ],
   "top_languages":[
      {
         "language_code":"en",
         "document_count":14570,
         "percentage":53.31
      },
      {
         "language_code":"ja",
         "document_count":2615,
         "percentage":9.57
      }
   ],
   "time_series":[
      {
         "date":"2020-08-01",
         "document_count":3092,
         "hours":[
            {
               "timestamp":"2020-08-01T00:00:00+01:00",
               "document_count":168
            }
         ]
      }
   ]
}
```

## Custom analytics

You can go beyond pre-defined analytics options using the custom analytics feature. This feature allows you to choose an analysis type, and then choose measures and dimensions to meet your need.

For every analysis you will need to specify an analysis type. Depending on the analysis type you choose you may need to specify a dimension and a measure.

### Parameters

When calling the custom analytics endpoint you need to provide:

* `start` and `end` - the time period you'd like to analyze (ISO8601 timestamps, excluding timezone/offset). *Note that the analysis will be inclusive of the start time and exclusive of the end time.*
* `tz` - An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.

You can also optionally specify a number of additional filters including:
- `sources` - the source(s) you'd like to analyze, for example `news` or `blogs`. If not provided, your request will analyze all sources. You can provide multiple values to analyze across multiple sources.
- `languages` - A primary language subtag from the IANA language tag registry, 'zh-Hant', 'zh-Hans' or 'zz'.
- `countries` - The two-letter ISO 3166-1 Alpha-2 country code, or 'ZZ'.
- `keywords` - A list of keywords to filter by.
- `filter_set` - The ID of a saved filter set to apply to your analysis. Must be a positive integer. If provided, only documents matching this filter set will be included.
- `emojis` - A list of emoji characters to filter by. Each emoji must be a valid Unicode emoji. For example, `["🔥", "🩵"]`
- `custom_categories` - One or more custom category IDs to filter by. Each must be a valid integer and non-empty.
- `author_lists` - One or more author list IDs to filter by. Each must be a valid integer and non-empty.

For example to run an analysis from the 1st to the 14th of February 2024, using UTC timezone, and filtered to content in English only:

```json
{
    "search_id": 12345,
    "tz": "UTC",
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "languages": [
        "en"
    ],
    "analysis": {
        "type": "document_count"
    }
}
```

*Note that the period you can analyze depend on your Meltwater API package. See the [Usage Limits](/guides/getting-started/usage-limits) page for more details.*

### Analytics types

The API supports the following analysis types:

* `document_count` - The total number of documents (or mentions)
* `count_unique` - The unique number of items based on a dimension, for example the unique number of countries
* `top_terms` - Breaks down mentions by a dimension, for example by sentiment
* `date_histogram` - Breaks down mentions by date, for example by day or month
* `measure_statistic` - Returns the total (sum), average, minimum, maximum for one or more measurements

The API also supports nested analysis with the following possible combinations:

* `date_histogram` -> `count_unique` (e.g. per day, the unique number of social authors posting)
* `date_histogram` -> `measure_statistics` (e.g. per day, the average reach of news content)
* `date_histogram` -> `top_terms` (e.g. per day, a breakdown of content sentiment)
* `date_histogram` -> `top_terms` -> `count_unique` (e.g. per day, per country, the unique number of social authors posting)
* `date_histogram` -> `top_terms` -> `measure_statistics` (e.g. per day, per country, the average reach of news content)
* `top_terms` -> `count_unique` (e.g. per country, the unique number of social authors posting)
* `top_terms` -> `measure_statistics` (e.g. per country, the average reach of news content)
* `top_terms` -> `top_terms` (e.g. per country, a breakdown of content sentiment)
* `top_terms` -> `top_terms` -> `count_unique` (e.g. per country, per language, the unique number of social authors posting)
* `top_terms` -> `top_terms` -> `measure_statistics` (e.g. per country, per language, the average reach of news content)

Examples towards the end of this guide show how you can combine analysis types.

### Supported measures and dimensions

See the [analytics options](/api-reference/analytics-options/listening#custom) page for details of which measures and dimensions are supported.

### Document count analysis

Use the `document_count` analysis type to get the total number of documents.

For example, this request returns the total number of documents for a two week period:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "document_count"
    }
}'
```

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "document_count"
    },
    "result": {
        "document_count": 18657
    }
}
```

Here the `document_count` field in the response is your analysis result.

### Count unique analysis

Use the `count_unique` analysis type to get a count of unique values for a dimension.

For example, this request returns the count of unique countries where mentions occur for the search:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "count_unique",
        "dimension": "location_country"
    }
}'
```

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "count_unique",
        "dimension": "location_country"
    },
    "result": {
        "document_count": 18657,
        "analysis": 43
    }
}
```

Here the `analysis` field in the response is your analysis result.

### Top terms analysis

Use the `top_terms` analysis type to get a breakdown of documents by a dimension.

For example, this request returns the number of documents broken down by the `shared_link` dimension, essentially it returns the top links shared within documents that match your search:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "top_terms",
        "dimension": "shared_link",
        "limit": 10
    }
}'
```

Note you can use the `limit` parameter to control how many results you want in the breakdown. This parameter defaults to 10, and has a maximum value of 100.

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "top_terms",
        "dimension": "shared_link",
        "limit": 10
    },
    "result": {
        "document_count": 18323,
        "analysis": [
            {
                "key": "https://link.com/to/article1",
                "document_count": 323,
                "percentage": 1.76
            },
            {
                "key": "https://link.com/to/article2",
                "document_count": 125,
                "percentage": 0.97
            }
        ]
    }
}
```

The API returns a breakdown by your chosen dimension returning the top results, each with the number of documents for that value, and what percentage of the documents for your search and time window match that result.

### Date histogram analysis

Use the `date_histogram` analysis type to get a breakdown of documents over time.

For example, this request returns the number of documents broken down by day:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "date_histogram",
        "granularity": "day"
    }
}'
```

The `granularity` parameter supports the following options:
* `hour` - supported for time windows of up to 7 days
* `day` - supported for time windows of up to 30 days (or 366 days for customers with the "Enterprise API", "Meltwater Insights API - Advanced", or "Meltwater Insights API - Premium" package)
* `week` - supported for time windows of up 1 year
* `month` - supported for time windows of up to 1 year

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "date_histogram",
        "granularity": "day"
    },
    "result": {
        "document_count": 18323,
        "analysis": [
            {
                "key": "2024-02-11T00:00:00",
                "document_count": 499,
                "percentage": 29.51,
                "change": 0
            },
            {
                "key": "2024-02-12T00:00:00",
                "document_count": 625,
                "percentage": 36.96,
                "change": 126
            }
        ]
    }
}
```

The API returns a breakdown by your chosen time granularity. For each time slice the API tells you the number of documents, the change in document count in comparison to the previous period, and what percentage of the documents for your search and time window are in that period.

### Measure statistic analysis

Use the `measurement_statistic` analysis type to get the total (sum), average, minimum and maximum value for a measurement.

For example, this request returns statistics for reach:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "measure_statistics",
        "measures": ["reach", "views"]
    }
}'
```

You can provide up to 3 measures for this analysis.

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "measure_statistics",
        "measures": ["reach", "views"]
    },
    "result": {
        "document_count": 18323,
        "analysis": {
            "reach": {
                "avg": 23564.99,
                "max": 59833.00,
                "min": 2344.00,
                "sum": 322530.00
            },
            "views": {
                "avg": 43.20,
                "max": 76.00,
                "min": 1.00,
                "sum": 546.00
            }
        }
    }
}
```

For each measure requested the API returns the average (mean) value, maximum value, minimum value and total value, for documents that match your requested search and time window.

### Date histogram with nested top terms analysis

The `date_histogram` analysis type supports `top_terms` as a nested analysis option.

For example the following request fetches the top shared links, for each day in a two week period:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "date_histogram",
        "granularity": "day",
        "analysis": {
            "type": "top_terms",
            "dimension": "shared_link",
            "limit": 10
        }
    }
}'
```

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "date_histogram",
        "granularity": "day",
        "analysis": {
            "type": "top_terms",
            "dimension": "shared_link",
            "limit": 10
        }
    },
    "result": {
        "document_count": 18323,
        "analysis": [
            {
                "key": "2024-02-11T00:00:00",
                "document_count": 499,
                "percentage": 29.51,
                "change": 0,
                "analysis": [
                    {
                        "key": "https://link.com/to/article1",
                        "document_count": 323,
                        "percentage": 1.76
                    },
                    {
                        "key": "https://link.com/to/article2",
                        "document_count": 125,
                        "percentage": 0.97
                    }
                ]
            }
        ]
    }
}
```

The API returns a breakdown by your chosen time granularity. For each time slice the API provides a breakdown of your chosen dimension, providing the number of documents for the dimension value, and what percentage of the documents for your search and time window are in that period and match the dimension value.

### Top terms with nested top terms analysis

The `top_terms` analysis type supports `top_terms` as a nested analysis option so that you can perform a 2-level breakdown.

For example, this request would fetch the top shared links, and the language of the documents they are shared within:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/analytics/12345/custom \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "analysis": {
        "type": "top_terms",
        "dimension": "shared_link",
        "limit": 10,
        "analysis": {
            "type": "top_terms",
            "dimension": "language",
            "limit": 10
        }
    }
}'
```

Note you can use the `limit` parameter to control how many results you want in the breakdown. This parameter defaults to 10, and has a maximum value of 100.

The response from the API will look as follows:

```json
{
    "start": "2024-02-01T00:00:00",
    "end": "2024-02-15T00:00:00",
    "tz": "UTC",
    "search_id": 12345,
    "analysis": {
        "type": "top_terms",
        "dimension": "shared_link",
        "limit": 10,
        "analysis": {
            "type": "top_terms",
            "dimension": "language",
            "limit": 10
        }
    },
    "result": {
        "document_count": 18323,
        "analysis": [
            {
                "key": "https://link.com/to/article1",
                "document_count": 323,
                "percentage": 1.76,
                "analysis": [
                    {
                        "key": "en",
                        "label": "English",
                        "document_count": 23,
                        "percentage": "0.45"
                    }
                ]
            }
        ]
    }
}
```

The API returns a breakdown by your chosen top-level dimension, then further breaks this result down by your second-level dimension. Note that the percentage in the 2nd level of analysis compares the number of matching documents for that key with the number of documents for the parent key.

---

## Datastreams Document Verification


When a new document is pushed to your `target_url`, you may want to verify that the document is actually coming from Meltwater.

For each call to your `target_url` we provide a signature header `X-Hub-Signature`.
This signature is a hash of the JSON payload that we are sending you. More specifically this signature is a HMAC encoded, 40 character long hexadecimal sha1 with a sha1= prefix.

Example: `X-Hub-Signature: sha1=9065c86cefbd8f0cc82f888f8c520b7f7c0b5157`

## Exchanging the shared secret

In order to use a signature, we need to establish a shared secret between you (the consumer) and the Meltwater API. We provide two approaches for how to exchange the shared secret:

**(1) You provide the shared secret when creating a data stream**

Use the header `X-Hook-Secret` with the `POST /v3/hooks` endpoint. The shared secret is limited to minimum 16 and maximum 64 characters.

**(2) We auto-generate a shared secret when you are creating a data stream**

If you don't provide the header `X-Hook-Secret`, we will auto-generate a random secret for you.

In both approaches, you will be able to obtain the shared secret from the response header `X-Hook-Secret` when using the `POST /v3/hooks` endpoint.

## Verifying the signature

Now that you know how to obtain the signature and the secret, you need to verify the signature in your service.

You do so by calculating the signature of the payload yourself, using the secret as a decryption key. If your calculated signature matches the `X-Hub-Signature` that you received, then you know that the messages clearly comes from the Meltwater API.

Here some examples in different programming languages of how to calculate the signature yourself:

### Using Benthos/Bloblang

```yaml
pipeline:
  processors:
    # Signature verification
    - bloblang: |
        # Delete the message if the HOOK_SECRET env variable is set and the signatures don't match
        root = if "${HOOK_SECRET:''}" != "" && meta("X-Hub-Signature") != "sha1=%s".format(content().hash("hmac_sha1","${HOOK_SECRET:''}").encode("hex")) {
            deleted()
        }
```

### Using Ruby

```ruby
require 'openssl'
secret = '11114f34565bd3b2247d123762de0234231eb181'
payload = '[{"my": "json_payload"}]'
OpenSSL::HMAC.hexdigest('sha1', secret, payload)
# => "9065c86cefbd8f0cc82f888f8c520b7f7c0b5157"
```

### Using Elixir

```elixir
secret = "11114f34565bd3b2247d123762de0234231eb181"
payload = "[{\"my\": \"json_payload\"}]"
signature = :sha |> :crypto.hmac(secret, payload) |> Base.encode16 |> String.downcase
# "9065c86cefbd8f0cc82f888f8c520b7f7c0b5157"
```

### Using Bash

```bash
SECRET='11114f34565bd3b2247d123762de0234231eb181'
PAYLOAD='[{"my": "json_payload"}]'
echo -n "$PAYLOAD" | openssl dgst -sha1 -hmac "$SECRET" -hex
# "9065c86cefbd8f0cc82f888f8c520b7f7c0b5157"
```

---

## Exporting Mentions


In this tutorial we'll cover the basics of creating an **earned media** export using the API.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* A Saved Search in your Meltwater App account

## Types of export

There are two types of exports:

* **One-time exports** - these exports are run once, the data will not be refreshed automatically.
* **Recurring exports** - these exports are run on a schedule you specify. Each time the export runs the data for the export is overwritten.

## Obtaining a Meltwater search

Exports are created with an existing Meltwater search.

*In this tutorial we'll cover using an existing search, but you can create / edit searches using the API. See the [Managing Saved Searches](/guides/listening/managing-searches) guide for more details.*

To create an export you need to provide the `id` of the required search. You can use the `GET /v3/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "searches": [
    {
      "updated": "2023-01-10T14:42:10.000Z",
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}
```

## Understanding common export options

The following options are available for both one-time and recurring exports.

### Choosing an output template

The API allows you to choose from a selection of templates for your export, which you specify using the `template` field in your export request. The available templates are documented on the [Export & Streaming Output Templates page](/api-reference/templates/overview).

We recommend using the general purpose "API JSON" template for most integrations, as this includes all the data fields most customers need.

To use the "API JSON" template you would use the following as part of your export request:

```json
"template": {
  "name": "api.json"
}
```

*If you do not specify a template in your request the API will use the legacy output template as documented [here](/api-reference/templates/overview).*

### Controlling data volumes using sampling

When creating an export, you can provide optional sampling parameters to set a maximum document count and/or percentage sample.

This feature allows you to control the amount of documents you export, and so stay within your export limits, plus also export representative data for high-volume topics. Sampling is supported for both one-time and recurring exports, and returns a random sample across the matching documents that would be in a full export.

There are two parameters that control sampling of results:

* `count` - the maximum number of documents you'd like to retrieve. Defaults to `2,000,000`. Maximum value is 2 million.
* `percentage` - the percentage of results you'd like to retrieve. Defaults to `100`.

*Please note, that the sampling process is approximate in that the number of results will be within ±10% of your parameters.*

**Example 1 -** return a 1% sample of matching documents:
```json
"sample": {
  "percentage": 1.0
}
```

**Example 2 -** return up to 50,000 documents:
```json
"sample": {
  "count": 50000
}
```

**Example 3 -** return a 10% sample of documents, but if this results in more than 1,000 documents, reduce the sample rate to limit the total results to 1,000 documents:
```json
"sample": {
  "count": 1000,
  "percentage": 10.0
}
```

By default if you do not specify these parameters your export will contain up to 2 million documents as a 100% sample. If your export request matches more than 2 million documents, then it will be sampled down to 2 million results.

### Classification and filtering using Custom Categories

[Custom Categories](https://community.meltwater.com/explore-44/custom-categories-in-explore-7898?tid=7898&fid=44) are a feature supported in Explore which allows you to categorize documents based upon a boolean query.

*Note that currently the API doesn't support creating or managing Custom Categories, so they must be managed within Explore.*

You can use Custom Categories to both classify and filter export results.

To fetch the list of Custom Categories in your account call the `GET /v3/custom_categories` endpoint:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/custom_categories" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "count": 2,
  "custom_categories": [
    {
      "id": 123,
      "name": "Japanese cars",
      "type": "include"
    },
    {
      "id": 456,
      "name": "German cars",
      "type": "exclude"
    }
  ]
}
```

Use the IDs given in this response to specify categories when creating your one-time or recurring export.

Providing a list of Custom Category IDs in your export request will classify results with the categories. The `custom.custom_categories` field for each document in the result will tell you which categories were matched.

Additionally, you can specify whether to return only documents with at least one category match by specifying the `filter` parameter as `true`. This option defaults to `false` meaning all results are returned regardless of whether they match a category specified.

As an example, this configuration would classify export results with the categories `123` and `321`, and only return documents which match at least one category:

```json
{
  "custom_categories": {
    "ids": [
      123,
      321
    ],
    "filter": true
  }
}
```

## Creating a one-time export

One-time exports are created using the [`POST /v3/exports/one-time`](/api-reference/api-reference-overview) endpoint. You need to provide a `start_date`, `end_date`, `format` and a `search_id` to create an export.

*Note that times are provided in UTC timezone. This is required for one-time exports.*

```shell
curl --location 'https://api.meltwater.com/v3/exports/one-time' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apikey: **********' \
--data '{
    "onetime_export": {
            "search_ids": [<search_id>],
            "start_date": "2024-01-01T00:00:00Z",
            "end_date": "2024-02-01T00:00:00Z",
            "sample": {
                    "count": 1000,
                    "percentage": 10.0
            },
            "template": {
                    "name": "api.json"
            }
    }
}'
```

Example response:

```json
{
  "onetime_export": {
    "updated_at": "2024-04-02T11:23:40.000000",
    "tags": [],
    "status_reason": "Export run has not completed yet",
    "status": "PENDING",
    "start_date": "2024-01-01T00:00:00.000000Z",
    "searches": [
      {
        "id": "<search_id>",
        "name": "<search_name>"
      }
    ],
    "sample": {
      "count": 1000,
      "percentage": 10
    },
    "inserted_at": "2024-04-02T11:23:40.000000",
    "id": "<export_id>",
    "end_date": "2024-02-01T00:00:00.000000Z",
    "data_url": "<data_url>",
    "template": {
      "name": "api.json"
    }
  }
}
```

## Fetching one-time export results

You can check the status of a one-time export using the `GET /v3/exports/one-time/<export_id>` endpoint.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/exports/one-time/<export_id>" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
    "onetime_export": {
        "updated_at": "2024-04-02T11:24:32.000000",
        "tags": [],
        "status_reason": "",
        "status": "FINISHED",
        "start_date": "2024-01-01T00:00:00.000000Z",
        "searches": [
          {
            "id": "<search_id>",
            "name": "<search_name>"
          }
        ],
        "sample": {
            "count": 1000,
            "percentage": 10
        },
        "inserted_at": "2024-04-02T11:23:40.000000",
        "id": "<export_id>",
        "end_date": "2024-02-01T00:00:00.000000Z",
        "data_url": "<data_url>",
        "template": {
            "name": "api.json"
        }
    }
}
```

Once the status is `FINISHED` there will be results in JSON format at the `data_url`. If the status is still `PENDING` the `data_url` will return a `403` status code.

:::info Export execution time
The size of an export depends on how many results the search generates, and how large time window it covers. The larger the export, the longer it will take to generate - this can vary from a minute for small exports up to an hour for very large exports.
:::

## Understanding export results

When you specify a CSV template for your output, the `data_url` will point to a CSV file for you to access, with the CSV containing columns as specified on the [Export & Streaming Output Templates page](/api-reference/templates/overview).

For JSON templates, the structure of the result is as follows:

```json
{
   "request": {
        "company_id": "<the id of the account that owns the inputs used>",
        "count": "<number of results>",
        "export_id": "<the id of the export in the Meltwater system>",
        "inputs": ["<the inputs used for the export>"],
        "period": {
            "start": "<start of the export period requested>",
            "end": "<end of the export period requested>"
        },
        "status": "<status of the export>"
    },
    "docs": [
      "<an object for each document in the export, according to the chosen template>"
    ]
}
```

*Note that prior to the templates feature being introduced, exports used a legacy output format as described [here](/api-reference/templates/overview).*

## Creating a recurring export

Recurring exports run on a schedule you specify. Each time the schedule runs it overwrites the data provided at the `data_url`.

### Specifying a time window and schedule

When you create a recurring export you have a number of parameters you can use to control the schedule and the period of data each run should include.

The `window_time_unit` parameter sets the frequency of the schedule, you can choose:

- `DAY` - exports are run daily
- `WEEK` - exports are run weekly
- `MONTH` - exports are run monthly

The `window_size` allows you to specify the period of data to include in each export. Think of this value as multiple of the `window_time_unit` you chose. For example, specifying `window_time_unit` as `DAY` and `window_size` as `2` will set a recurring export to run **every day** which will include the last **2 days** of data in each run.

You can use the following parameters to specify precisely the window of data included for each run:

- For daily exports you can specify the daily start time with `window_time`
- For weekly exports you can specify the day of the week with `window_weekday` and start time with `window_time`
- For monthly exports you can specify the day of the month with `window_monthday` and start time with `window_time`

Note that you can use the `timezone` parameter to specify the timezone for your `window_time`. The timezone must be a valid zone as detailed in the [IANA database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

As a full example, the following parameters create a recurring export that will run every day at 09:00 UTC including the last 7 days of data.

```json
{
    "window_time_unit": "DAY",
    "window_size": 7,
    "window_time": "09:00:00",
    "timezone": "Etc/UTC"
}
```

Default values for recurring export attributes are as follows:

- `window_time`: `"00:00:00"`
- `window_weekday`: `1` (Monday)
- `window_monthday`: `1`
- `timezone`: `Etc/UTC`

:::info Scheduling of recurring exports
Note that exports are executed by the platform 30 minutes after the end time of the required export period. This is to allow data to be ingested by the platform from providers.
:::

### Creating a recurring export via API

Recurring exports are created using the [`POST /v3/exports/recurring`](/api-reference/api-reference-overview) endpoint.

```shell
curl --location 'https://api.meltwater.com/v3/exports/recurring' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apikey: **********' \
--data '{
  "recurring_export": {
    "search_ids": [<search_id>],
    "window_time_unit": "DAY",
    "window_time": "09:00:00",
    "window_size": 7,
    "timezone": "Etc/UTC",
    "sample": {
      "count": 1000,
      "percentage": 10.0
    },
    "template": {
      "name": "api.json"
    }
  }
}'
```

Example response:

```json
{
  "recurring_export": {
    "updated_at": "2024-04-02T11:34:14.000000",
    "tags": [],
    "timezone": "Etc/UTC",
    "status_reason": "Export run has not completed yet",
    "status": "PENDING",
    "next_run_date": "2024-04-03T09:30:00Z",
    "searches": [
      {
        "id": "<search_id>",
        "name": "<search_name>"
      }
    ],
    "sample": {
      "count": 1000,
      "percentage": 10
    },
    "inserted_at": "2024-04-02T11:34:14.000000",
    "id": "<export_id>",
    "data_url": "<data_url>",
    "window_time_unit": "DAY",
    "window_size": 7,
    "window_time": "09:00:00",
    "template": {
      "name": "api.json"
    }
  }
}
```

## Fetching recurring export results

You can check the status of a recurring export using the `GET /v3/exports/recurring/<export_id>` endpoint.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/exports/recurring/<export_id>" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Once the status is `ACTIVE` there will be results in JSON format at the `data_url`. If the status is still `PENDING`, the `data_url` will still be available, but just contain an empty list of documents.

The first time an export is run for a recurring export the data is available at `data_url`. For subsequent runs the data will override previous results at the same `data_url`.

---

## Managing Searches(Listening)


You can use the Meltwater API to manage the earned media Saved Searches for your Meltwater account.

The [endpoints specification](/api-reference/api-reference-overview) details the available endpoints for creating, reading, updating and deleting searches.

## Listing Saved Searches

Saved Searches can be created by users in the Meltwater application or through the API.

To list your current Saved Searches you call the `GET searches` endpoint:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "searches": [
    {
      "updated": "2020-01-10T14:42:10.000Z",
      "name": "SpaceX",
      "id": 12345,
      "query": null
    }
  ]
}
```

In the response you can see the ID of each search, along with the name and when it was last updated.

## Getting a Saved Search

To get the details for an individual search you call the `GET searches/{id}` endpoint.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches/12345" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
    "search": {
        "updated": "2020-01-10T14:42:10.000Z",
        "id": 12345,
        "name": "SpaceX",
        "query": {
            "filter_set": null,
            "case_sensitivity": "no",
            "not_keywords": [],
            "any_keywords": [],
            "all_keywords": [
                "Spacex"
            ],
            "type": "keyword"
        }
    }
}
```

When you fetch a search the result includes the query.

## Creating a Saved Search

To create a Saved Search you call the `POST searches` endpoint, passing a search object as the payload. For example:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/searches" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence\")",
              "type": "boolean"
          }
      }
  }'
```

If your request is successful the API will respond with the `201` status code and the saved definition of the search, including the ID of the new search.

```json
{
  "search": {
    "updated": "2020-08-23T08:25:56.000Z",
    "query": {
      "type": "boolean",
      "case_sensitivity": "no",
      "boolean": "(\"business intelligence\")"
    },
    "name": "Example search",
    "id": 12346
  }
}
```

### Search object definition

The search object has the following fields:

* `name`: The name you want to give your search. *Note that you cannot have the same name for two different searches.*
* `query`: An object that defines your search query, explained below.

### Query object definition

There are three search query types supported by the Meltwater platform:

* `keyword`: use simple lists of keywords for your query
* `boolean`: use complex boolean expressions for your query
* `combined`: combine existing saved searches as a new query

An example keyword query, searching for all mentions of 'SpaceX' but excluding mentions of 'Richard Branson' would be:

```json
"query": {
    "type": "keyword",
    "not_keywords": [
      "Richard Branson"
    ],
    "any_keywords": [],
    "all_keywords": [
        "SpaceX"
    ],
    "case_sensitivity": "no"
}
```

An example boolean query, searching for the phrase 'business intelligence' would be:

```json
"query": {
    "type": "boolean",
    "boolean": "(\"business intelligence\")",
    "case_sensitivity": "no"
}
```

*The boolean syntax used for Meltwater searches is not covered in the developer documentation as it is core platform feature. To learn more about Meltwater's boolean search syntax please see the ["Boolean Training Guide"](https://docs.google.com/presentation/d/15TtEWr1uJGlJIbvXMcNOpnB_v6NxnirSY2028BlofNI/edit?slide=id.g25e700e3ef0_0_353).*

An example combined query, including all matches from searches `123` and `124`, but excluding matches from search `125` would be:

```json
"query": {
    "type": "combined",
    "not_searches": [125],
    "any_searches": [123,124],
    "all_searches": []
}
```

*For more details on combined searches, see the [Working with Combined Searches section](#working-with-combined-searches) below.*

## Updating a Saved Search

To update a search you call the `PUT searches/{id}` endpoint, passing a search object as the payload. For example:

```shell
curl -X PUT \
  --url "https://api.meltwater.com/v3/searches/12345" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search - updated",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence tools\")",
              "type": "boolean"
          }
      }
  }'
```

The search object has the same fields as when creating a search.

If your request is successful the API will respond with the `200` status code and the saved definition of the search.

**Please note that if you update a saved search created in the application by a user it may have a filter set applied. When updating a search with a filter set you need to be sure you are not removing the filter set applied. Read the section below on filters sets to learn more.**

## Deleting a Saved Search

To delete a search you call the `DELETE searches/{id}` endpoint. For example:

```shell
curl -X DELETE \
  --url "https://api.meltwater.com/v3/searches/12346" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

If your request is successful the API will respond with the `204` status code.

## Working with Filter Sets

Filter Sets are a feature in the Explore application which allow users to easily apply common filter configurations.

When you get a search from the API there is a field returned under `query` called `filter_set`. This can either be null (no filter set is applied to the search), or be an object with one of two types:

* `embedded`: a user in the application has applied filters to a search, but not a 'saved' filter set.
* `saved`: a saved filter set is applied to the search.

For 'saved' filter sets there are two sub-types supported by the platform:

* `custom`: a filter set saved by a customer
* `quickpick`: a filter set defined by Meltwater

Currently the API allows you to list saved filter sets, and apply these when creating and updating saved searches. The API does not support creating, updating or deleting filter sets. Also, the API does not support applying un-saved / adhoc filters to searches at this time.

### Listing filter sets

You can list the filter sets available to you by calling the `GET filter_sets` endpoint:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/filter_sets?include_quickpicks=true" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
    "filter_sets": [
        {
            "id": 488068,
            "name": "My example filter set",
            "subtype": "custom",
            "type": "saved"
        },
        {
            "id": 583050,
            "name": "UK news",
            "subtype": "quickpick",
            "type": "saved"
        }
    ]
}
```

### Creating a search with a filter set

You can use saved filter sets when creating saved searches, by passing a `filter_set` object as part of the query object, passing `saved` as the type and the id of the filter set:

```json
{
    "type": "boolean",
    "case_sensitivity": "no",
    "boolean": "(\"business intelligence\")",
    "filter_set": {
        "type": "saved",
        "id": 488069
    }
}
```

### Updating a search with a filter set

When you update a search with a filter set applied you need to make sure you are preserving the filter set (if this is appropriate).

If the saved search has a `saved` filter set applied, make sure you pass in the filter set object with the filter set id.

```json
"filter_set": {
    "type": "saved",
    "id": 488069
}
```

If the saved search has a `embedded` filter applied, you can preserve the filter settings by passing in a filter set object with type `embedded`:

```json
"filter_set": {
    "type": "embedded"
}
```

## Working with Combined Searches

When you manage Combined Searches through the API, the API assumes that the IDs you provide are for Saved Searches as this was the original design of this feature in the application. Combined Searches now allow you to also use Filter Sets and Custom Categories as part of your combined search definitions.

To work with these new concepts, our API endpoints now support a new optional parameter (`expand_combined`), which when set to true includes the type of search object in API calls and responses.

### Creating a Combined Search using different search types

As an example, the following request creates a combined search which includes data from a Saved Search, but uses a Custom Category as an exclusion filter:

```shell
curl -X POST \
    --url "https://api.meltwater.com/v3/searches?expand_combined=true" \
    --header 'Content-Type: application/json' \
    --header "apikey: **********" \
    --data-raw '{
        "search": {
        "name": "Example search",
        "query": {
            "filter_set": null,
            "not_searches": [
                {
                    "id": 456,
                    "type": "CUSTOM_CATEGORY"
                }
            ],
            "any_searches": [
                {
                    "id": 123,
                    "type": "SEARCH"
                }
            ],
            "all_searches": [],
            "type": "combined"
        }
    }
}'
```

The API would return the following response:

```json
{
    "search": {
        "updated": "2020-08-23T08:25:56.000Z",
        "query": {
            "filter_set": null,
            "not_searches": [
                {
                    "id": 456,
                    "type": "CUSTOM_CATEGORY"
                }
            ],
            "any_searches": [
                {
                    "id": 123,
                    "type": "SEARCH"
                }
            ],
            "all_searches": [],
            "type": "combined"
        },
        "name": "Example search",
        "id": 12346
    }
}
```

Available values for `type` are `SEARCH`, `FILTER_SET` and `CUSTOM_CATEGORY`.

You can update a search using the same optional parameter and types.

### Fetching Combined Searches with search types included

You can also use the `expand_combined` query parameter when fetching searches to include the extra context.

```shell
curl -X GET \
    --url "https://api.meltwater.com/v3/searches/12346?expand_combined=true" \
    --header "Accept: application/json" \
    --header "apikey: **********"
```

Example response:

```json
{
    "search": {
        "updated": "2020-08-23T08:25:56.000Z",
        "query": {
            "filter_set": null,
            "not_searches": [],
            "any_searches": [
                {
                    "id": 123,
                    "type": "SEARCH"
                }
            ],
            "all_searches": [
                {
                    "id": 987,
                    "type": "CUSTOM_CATEGORY"
                }
            ],
            "type": "combined"
        },
        "name": "Example search",
        "id": 12346
    }
}
```

## Boolean query complexity

Using boolean syntax you can create very complex queries. The Meltwater platform supports complex searches, but to protect the platform and other customers we do estimate the complexity of your search and will prevent searches which are extremely complex.

When you create or update a search through the API, if the query is too complex you will receive a `422` error. The error object for 422 contains a `meta` object which can be used to distinguish between different types of unprocessable requests.

To prevent this from happening, please follow these guidelines:

* Try to avoid using excessive wildcards and `NEAR`s.
* Maximum of **5,000 terms** (e.g. `a OR b AND c AND ...`)
* Maximum **query length of 80,000 characters**

We keep the right to modify these limitations further in the future. While it is of course our goal to make our search system as powerful as possible, it might be required for us in the future to enforce the above limits or modify them. We will announce this accordingly to customers that are affected by these limits.

---

## Overview(Listening)

# Listening Overview

In this guide we'll introduce you to key Listening concepts of the Meltwater API and platform.

## Meltwater platform

The **Meltwater platform** ingests and enriches data from a wide variety of sources, including news and social platforms. Data is enriched by a set of enrichments (sentiment, language, key phrases, etc.) and stored in a consistent data schema. Listening data is held in a central store. The Meltwater application accesses these data stores to provide application features. The Meltwater API is built upon the same platform and data stores.

The Meltwater API allows you to export, stream and analyze listening data. If you are using one of our [BI connectors](/guides/integrations/overview) this is calling the API behind the scenes for you, using your API credentials.

Broadly speaking you can access the same data through the API as a user sees in the application. However, due to the agreements we have with data providers there are some limitations on what data can be provided through the API.

*For example, in the application we can provide the text of X posts, whereas due to X's terms of service in the API we can only provide the ID of a post. An API customer needs to call the X API to rehydrate the post in order to get the post text.*

:::info What is earned media?
"Earned media" is another term for the data available in the listening data set. API contracts state limits for using this data, such as how many 'earned media documents' you can export in a month and how many analysis calls you can make per day.
:::

## Saved Searches

To export or stream content, or run analytics on listening data, you will need to start with a Saved Search. A Saved Search is a query that defines which documents in the platform should be matched for the request.

Documents that are matched by a Saved Search are called **Mentions**.

A Saved Search can be created in the Meltwater application using the **Explore** product, or by using the API.

Typically this will be a boolean query. For example, if you wanted to find news articles or social posts that mention Apple watches you may write:

`(apple AND (iphone OR iwatch)) NOT ("apple sauce" OR "apple juice" OR "apple orchard*")`

You may already have searches saved in the Meltwater application that you'd like to use with the API. If you'd like to create searches using the API take a look at the [Managing Saved Searches](/guides/listening/managing-searches) guide.

### Searching & Exporting Mentions

You can fetch mentions using the API using either the search or export feature. You should only use the search feature to fetch small numbers of mentions. To fetch large numbers of mentions use the export feature.

The fields available for mentions depend on the source of the mention and the template you choose for your export. See the [Content Output Templates](/api-reference/templates/overview) page for full details.

#### Searching Mentions

To search mentions you need to provide a Saved Search ID and a time window. You can choose to sort mentions using various fields, and can paginate through results.

To learn how to search mentions using the API see the [Searching Mentions guide](/guides/listening/searching-mentions).

#### Exporting Mentions

To export mentions using the API you need to provide one or more Saved Search IDs and a time window for the export.

When you run an export this will be placed in a queue (each API customer has a separate queue). You can view the status of your exports by calling the API.

When the export runs it will return any mentions found in the data store that match the search criteria within the time window specified.

The API allows you to run one-time and recurring exports:

* **One-time exports** - these exports are run once, the data will not be refreshed automatically.
* **Recurring exports** - these exports are run on a schedule you specify. Each time the export runs the data for the export is overwritten.

To learn how to create exports using the API see the [Export API & Console guide](/guides/listening/exporting-mentions).

### Analyzing Mentions

To run analytics on listening data using the API you need to provide a Saved Search ID and a time window. Depending on the type of analysis you may need to provide additional parameters such as the source to analyze.

When you run an analysis you are analyzing the documents that match your search criteria. These are the same documents that would be returned if you ran an export with the same criteria. Unlike exports, analytics requests are synchronous, therefore they are typically returned in a few seconds.

To understand what analytics are available see the [Analytics Options](/api-reference/analytics-options/listening) page.

To learn how to request analytics using the API see the [Analyzing Mentions guide](/guides/listening/analyzing-mentions).

### Streaming Mentions

You can stream mentions in real-time using the **Data Streams** feature, if this is included in your API package.

To stream mentions you need to provide a Saved Search ID, and a destination URL for where you would like data pushed to. A data stream pushes mentions for a single saved search.

When you create a new data stream the platform will listen for any new documents coming in to the platform that match your search. Any matches will immediately be pushed to your destination URL. These matches (documents) will contain a number of fields such as the URL, title, content, sentiment, and so on.

The fields available for documents depend on the source of the document. See the [Content Output Templates](/api-reference/templates/overview) page for full details.

The quickest way to get familiar with data streaming is by reading the [Streaming Mentions guide](/guides/listening/streaming-mentions).

---

## Rehydrating X Posts


Due to X terms of service, when you export X posts from the Meltwater API you will receive only the ID of the post and the post's author. In this guide we look at how you can use these IDs to fetch full details from the X API, in a process called 'rehydration'.

*This process does add a step to your process when using the Meltwater API, but it means that both Meltwater and our clients are compliant with the required terms.*

## Exported X posts

When you run an export, any X posts that are returned will not have content or the details of the X author. This is intentional because of the terms X enforces. To get the content of a post (and many other useful fields) you will need to rehydrate each post using the X API.

Each post returned from the Meltwater API will have the following ID fields:

```json
{
  "document_external_id": "1228393702244134912",
  "document_authors": [
    {
      "author_external_id": "1000001234567891234"
    }
  ]
}
```

Use the value of the `document_external_id` field to fetch post details from the X API.

Use the value of the `author_external_id` field to fetch author details from the X API.

## Requesting access to the X API

To be able to call the X API you must first [request access](https://developer.twitter.com/en/docs/twitter-api/getting-started/getting-access-to-the-twitter-api).

*Details of this process are documented by X and are not covered here.*

X have recently updated their API packaging and pricing. Please see the official X API documentation for [up-to-date pricing details](https://developer.twitter.com/en/docs/twitter-api).

## Rehydrating posts

You can fetch up to `100` posts in a single API call using the `GET /2/tweets` endpoint on the X API.

The process is extensively documented on the X developer site - [Tweet lookup](https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/introduction).

The limits applied to this endpoint vary by the authentication method you use, but at time of writing the limits would allow you to rehydrate millions of posts per month.

When you call the endpoint you express which fields you'd like included in the response. By default the `id` and `text` fields are returned, but you can also request 'expansion' on fields such as the author.

For example, this request returns when each post was created, the author id, and additional details about the author:

```shell
curl -X GET \
  --url "https://api.twitter.com/2/tweets?ids=<POST_IDs>&tweet.fields=created_at&expansions=author_id&user.fields=created_at" \
  --header "Authorization: Bearer $BEARER_TOKEN"
```

This would return:

```json
{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2020-02-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "text": "What did the developer write in their Valentine's card?\n  \nwhile(true) {\n    I = Love(You);  \n}"
    },
    {
      "author_id": "2244994945",
      "created_at": "2020-02-12T17:09:56.000Z",
      "id": "1227640996038684673",
      "text": "Doctors: Googling stuff online does not make you a doctor\n\nDevelopers: https://t.co/mrju5ypPkb"
    },
    {
      "author_id": "2244994945",
      "created_at": "2019-11-27T20:26:41.000Z",
      "id": "1199786642791452673",
      "text": "C#"
    }
  ],
  "includes": {
    "users": [
      {
        "created_at": "2013-12-14T04:35:55.000Z",
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}
```

We won't cover all the options here as they are covered in the X documentation, but in summary the X API allows you to be very specific about the fields you'd like returned, and allows you to fetch author details alongside post fields in one request.

## Rehydrating authors

For most use cases rehydrating posts will give all the details needed. However, it is also possible to lookup authors (users) using the X API.

You can fetch up to `100` users in a single API call using the `GET /2/users` endpoint on the X API.

The process is extensively documented on the X developer site - [User lookup](https://developer.twitter.com/en/docs/twitter-api/users/lookup/introduction).

Similar to the post lookup you can specify which fields you'd like fetched, but as a basic example you can fetch users with the following call:

```shell
curl -X GET \
  --url "https://api.twitter.com/2/users?ids=2244994945,6253282" \
  --header "Authorization: Bearer $BEARER_TOKEN"
```

This would return:

```json
{
  "data": [
    {
      "id": "2244994945",
      "username": "TwitterDev",
      "name": "Twitter Dev"
    },
    {
      "id": "6253282",
      "username": "Twitter",
      "name": "Twitter"
    }
  ]
}
```

---

## Searching Mentions(Listening)


In this tutorial we'll get you up and running to make your first search calls.

:::info Should I use the API search or export feature?
The search feature has recently been added to the API to support use cases where a small number of mentions are needed. For example, if you'd like to display the top 50 mentions of your brand on a dashboard.

The [export feature](/guides/listening/exporting-mentions) remains the best method for fetching large numbers of documents.
:::

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* A Saved Search in your Meltwater App account

## Obtaining a Meltwater search

To search mentions you need to refer to an existing Meltwater saved search.

*In this tutorial we'll cover using an existing search, but you can create / edit searches using the API. See the [Managing Saved Searches](/guides/listening/managing-searches) guide for more details.*

You need to provide the `id` of the required search. You can use the `GET /v3/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "searches": [
    {
      "updated": "2018-01-10T14:42:10.000Z",
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}
```

## Search requests

You use the `POST /v3/search/[search id]` endpoint to fetch mentions.

Here's an example request which we'll break down below in detail, given the number of options available:

```shell
curl --request POST \
  --url 'https://api.meltwater.com/v3/search/1234' \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "start": "2025-05-01T00:00:00",
  "end": "2025-05-08T00:00:00",
  "page": 1,
  "page_size": 100,
  "sort_by": "date",
  "sort_order": "desc",
  "tz": "UTC",
  "template": {
    "name": "api.json"
  },
  "languages": ["en", "fr"]
}'
```

### Time period

For every request you need to specify a time window:

* `start` and `end` - the time period you'd like to analyze (ISO8601 timestamps, excluding timezone/offset). *Note that the search will be inclusive of the start time and exclusive of the end time.*
* `tz` - An identifier from the IANA TimeZone Database (tzdb), or a timezone offset, from UTC.

The period you can search depend on your Meltwater API package. See the [Usage Limits](/guides/getting-started/usage-limits) page for more details. You can track the number of documents returned from your searches using the `usage` endpoint. See the guide on [Accessing Usage Statistics](/guides/getting-started/accessing-usage-statistics) for more details.

*Note that the timezone you choose will not impact the timezone of dates and times in the search results. These will always be in UTC.*

### Output options

You can also choose from various options to control output, sorting and pagination:

* `page` - the page of results to fetch. Defaults to `1`, max is `10`.
* `page_size` - the number of searches to fetch. Defaults to `10`, max is `100`.
* `sort_by` - The sort field of results, one of `date`, `reach`, `engagement`, `social_echo`, `relevance`, `prominence`, `country`, `sentiment`, `language`, `title`, or `views`. Defaults to `date`.
* `sort_order` - The sort order of results, either `asc` (ascending) or `desc` (descending). Defaults to `desc`.
* `template` - The template you wish the documents to be formatted in. Defaults to `api.json`.

The feature currently supports the `api.json` and the `legacy` JSON output templates. See the [Content Output Templates](/api-reference/templates/overview) page for details of output fields.

### Filtering

You can also apply additional filters which will be applied on top of your chosen search:

* `sources` - the source(s) you'd like to analyze, for example `news` or `blogs`.
* `languages` - Language subtags from the IANA language tag registry, 'zh-Hant', 'zh-Hans' or 'zz'.
* `countries` - Two-letter ISO 3166-1 Alpha-2 country codes, or 'ZZ'.
* `sentiments` - The sentiment of documents to include. Possible values are `positive`, `negative`, and `neutral`.
* `keywords` - A list of keywords to filter by.
* `filter_set` - The ID of a saved filter set to apply to your search. Must be a positive integer. If provided, only documents matching this filter set will be included.
* `emojis` - A list of emoji characters to filter by. Each emoji must be a valid Unicode emoji. For example, `["🔥", "🩵"]`
* `custom_categories` - One or more custom category IDs to filter by. Each must be a valid integer and non-empty.
* `author_lists` - One or more author list IDs to filter by. Each must be a valid integer and non-empty.

As an example the following parameters would fetch the first page of 100 results, ordered by date descending, output results using the `api.json` template, and filter to mentions in English and French only.

```json
{
    "page": 1,
    "page_size": 100,
    "sort_by": "date",
    "sort_order": "desc",
    "languages": ["en", "fr"],
    "template": {
        "name": "api.json"
    }
}
```

## Understanding search results

Mentions will be returned by the API in the following structure:

```json
{
    "start": "2025-05-01T00:00:00",
    "end": "2025-05-08T00:00:00",
    "tz": "UTC",
    "page": 1,
    "page_size": 100,
    "sort_by": "date",
    "sort_order": "desc",
    "languages": ["en", "fr"],
    "template": {
        "name": "api.json"
    },
    "search_id": 123,
    "result": {
        "document_count": 91,
        "documents": [
            {
                "author": {
                    "external_id": "123456789987654321"
                },
                "content": {
                    "body": "this is an example document"
                }
            }
        ]
    }
}
```

The API returns details of your request; search id, time window, pagination, sorting, template etc.

Then under `result` the API returns the total count of results for the search (`document_count`) and an array of documents (mentions) using the output template you requested.

---

## Streaming Mentions


In this tutorial we'll cover the basics of streaming real-time content through the API.

**Note that you need access to the "Data Streams" feature in your API package to use this feature.**

## Before you start

To run through this tutorial, you will need:

- A location that is able to accept HTTP POST requests
  - For this tutorial we use [webhook.site](https://webhook.site/) which is free to use
- Your Meltwater API token
- A Saved Search in your Meltwater App account

## Obtaining a Meltwater search

Hooks are created with an existing Meltwater search.

*In this tutorial we'll cover using an existing search, but you can create / edit searches using the API. See the [Managing Saved Searches](/guides/listening/managing-searches) guide for more details.*

To create a hook you need to provide the `id` of the required search. You can use the `GET /v3/searches` endpoint to list your current searches:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "apikey: **********"
```

Example response:

```json
{
  "searches": [
    {
      "updated": "2018-01-10T14:42:10.000Z",
      "name": "Elon Musk",
      "id": 2382415
    }
  ]
}
```

## Setup a destination service

You are going to need a service that accepts HTTP POSTs with `Content-type: application/json` and a JSON body. We expect your service to return HTTP status code 200 on success.

For this tutorial we are going to use [webhook.site](https://webhook.site/) as a replacement for your own server.

If you already have a destination service, you can skip ahead to step 4.

Go to [webhook.site](https://webhook.site/) you should be presented with a dashboard where you will see events being delivered. Copy "your unique url" this is your destination, we will refer to it as the `<target_url>`.

To make sure your webhook.site endpoint is working, make a curl call to it:

```shell
curl -X POST -i -d "fizz=buzz" "<target_url>"
```

The response should be similar to following:

```
HTTP/1.1 200 OK
Server: nginx/1.14.2
Content-Type: text/plain; charset=UTF-8
Transfer-Encoding: chunked
Vary: Accept-Encoding
X-Request-Id: 2c061fd0-f465-11eb-9a03-0242ac130003
X-Token-Id: 28c9f8c8-f465-11eb-9a03-0242ac130003
Cache-Control: no-cache, private
Date: Tue, 03 Aug 2021 14:14:06 GMT
```

If you check back on the webhook.site you should see your request. Your destination is set up! Let's proceed and create a hook.

## Choosing an output template

The API allows you to choose from a selection of templates for your data stream, which you specify using the `template` field in your request. The available templates are documented on the [Export & Streaming Output Templates page](/api-reference/templates/overview).

We recommend using the general purpose "API JSON" template for most integrations, as this includes all the data fields most customers need.

To use the "API JSON" template you would use the following as part of your request:

```json
"template": {
  "name": "api.json"
}
```

*If you do not specify a template in your request the API will use the legacy output template as documented [here](/api-reference/templates/legacy-json).*

## Creating a data stream

With the destinations target URL primed and ready for data, we are now going to setup a data stream using the search id we looked up previously.

**Note that for historical reasons, data streams are called 'hooks' in the API endpoints.**

Select one `<search_id>` from any of your searches and run following request to setup a data stream:

```shell
curl --location 'https://api.meltwater.com/v3/hooks' \
--header 'apikey: **********' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "search_id": <search_id>,
    "target_url": "<target_url>",
    "template": {"name": "api.json"}
}'
```

As response you will receive the created data stream with its id (note the `<hook_id>`), e.g.:

```json
{
  "search_id": "<search_id>",
  "target_url": "<target_url>",
  "updated": "2024-01-01T05:57:47.00Z",
  "hook_id": "<stream_id>",
  "template": {"name": "api.json"},
  "version": "v2",
  "status": "PENDING",
  "status_reason": "Hook is in a starting state and documents will start being sent shortly"
}
```

## Understanding streamed results

Each time a batch of documents (1 or more) match your search, the Meltwater API will deliver a JSON payload to your target URL. The structure of the payload is as follows:

```json
{
    "request": {
        "company_id": "<the id of the account that owns the inputs used>",
        "hook_id": "<the id of the stream/hook in the Meltwater system that pushed the data>",
        "inputs": ["<the inputs used for the stream, ie. the search>"]
    },
    "documents": [
      "<an object for each document, according to the chosen template>"
    ]
}
```

*Note that prior to the templates feature being introduced, streams used a legacy output format as described [here](/api-reference/templates/legacy-json).*

## Verifying incoming search results

Depending on the volume of results your search produces, you should be receiving incoming results to your `<target_url>`.

For your production setup you may want to verify the payload signature, see details in [Document Verification](/guides/listening/datastreams-document-verification).

## Troubleshooting

Start by taking a look at the data streams section of our [Frequently Asked Questions](/help/faqs#data-streams).

*No results?* If you do not see any incoming requests for some time and you suspect something is not quite working please contact our [support team](/help/support).

You can simulate a webhook request from the Meltwater API with following cURL call. This is a typical request that your `target_url` should expect to receive.

Try making this call from outside your own network to verify there's no network restrictions preventing external requests reaching your target_url.

```shell
curl <target_url> \
  -X POST \
  -H "Content-Type: application/json" \
  -d @- << EOF
[
  {
    "source_reach": 712,
    "source_id": "C054DBBA56E1722EFEC5BF468DF229E8",
    "source_name": "Myinforms",
    "source_country_code": "us",
    "source_subregion": "Pennsylvania",
    "source_ave": 6.59,
    "metadata": {
      "search_name": "hello",
      "search_id": 1234,
      "hook_id": "0a815fa3ee87489de1b932f178541f80c1f1038c",
      "company_id": "company_id"
    },
    "source_information_type": "news",
    "document_url": "http://myinforms.com/en-us/a/43897824-musk-throws-pie-at-naysayers-as-tesla-posts-rare-profit/",
    "document_title": "Musk Throws 'Pie' at Naysayers as Tesla Posts Rare Profit",
    "document_sentiment": "negative",
    "document_publish_date": "2016-02-01T05:10:14.371Z",
    "document_language_code": "en",
    "document_key_phrases": ["fourth quarter"],
    "document_opening_text": "Tesla Motors Inc. posted an unexpected profit.",
    "document_image_link": "http://i1.myinforms.com/300x200/default.jpg",
    "document_id": "MweugEjvEhiuFbQQmid40Gs1Y-I",
    "document_hit_sentence": "Musk Throws 'Pie'",
    "document_matched_keywords": ["Musk", "Tesla"],
    "document_authors": [{"name": "John Doe", "author_information_type": "news"}]
  }
]
EOF
```

## Listing active hooks

You can query for all active hooks you have created so far:

```shell
curl -v -XGET \
  --url "https://api.meltwater.com/v3/hooks" \
  --header "apikey: **********"
```

The response will provide a list of hooks with `<search_id>`, your defined `<target_url>` and the `<hook_id>`:

```json
{
  "hooks": [
    {
      "search_id": "<search_id>",
      "hook_id": "<hook_id>",
      "target_url": "<target_url>",
      "updated": "2024-02-02T13:55:13Z",
      "template": {"name": "api.json"},
      "version": "v2",
      "status": "ACTIVE",
      "status_reason": ""
    }
  ]
}
```

## Deleting your hook

You have verified your hook is working and you are receiving results. You now plan to stop receiving results by deleting the hook again. All you need to do is to provide the `<hook_id>` in following `curl` request:

```shell
curl -v -XDELETE \
  --url "https://api.meltwater.com/v3/hooks/<hook_id>" \
  --header "apikey: **********"
```

The response should give back `HTTP/1.1 204 No Content`.

---

## Tagging Earned Media


In this tutorial we'll get you up and running with adding and removing tags from earned media documents. We'll also explain later in the guide how you can create new tags, and remove tags from your Meltwater account using the API.

## Why would you add tags to documents?

By using tags you can add your own classification to documents in the Meltwater system.

For example, you might build a solution that exports documents from our system, runs the documents through your own classification model, then write tags back to the documents in our system to reflect this classification.

The tags you add to the documents are held privately for your account, and can be used in dashboards and reports customising your data analysis.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* A Saved Search in your Meltwater App account

## Fetching your existing tags in your account

Before you add new tags to documents, you can use the API to fetch the list of tags you already have in your account.

Use the `GET /v3/tags` endpoint to list your current tags:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/tags" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "tags": [
    {
      "id": 123456,
      "name": "my tag"
    }
  ]
}
```

## Obtaining documents for tagging

To be able to add (or remove) tags from documents you will need to know the IDs of the documents you want to alter.

Typically customers would fetch documents using earned media exports or streaming. Take a look at the following guides to learn more:

* [Exporting Earned Media](/guides/listening/exporting-mentions)
* [Streaming Earned Media](/guides/listening/streaming-mentions)

Documents received through exports or streams will include a document ID you can use for your tagging calls.

## Adding tags to documents

To add tags to documents use the `POST /v3/documents/add_tags` endpoint.

The endpoint requires a list of document IDs (up to 100), and a list of tags (up to 100):

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/documents/add_tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_ids": ["abcdef123456", "abcdef123457"],
    "tags": [
        { "id": 243, "name": "my tag" },
        { "id": 456, "name": "my tag 2" }
    ]
}'
```

If the tags are successfully applied you will receive a `202` status code from the API.

## Removing tags from documents

To remove tags from documents use the `POST /v3/documents/remove_tags` endpoint.

The endpoint requires a list of document IDs (up to 100), and a list of tags (up to 100):

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/documents/remove_tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_ids": ["abcdef123456", "abcdef123457"],
    "tags": [
        { "id": 243, "name": "my tag" },
        { "id": 456, "name": "my tag 2" }
    ]
}'
```

If the tags are successfully removed you will receive a `202` status code from the API.

## Creating new tags in your account

In addition to adding and removing tags from documents, you can also create and remove tags present in your Meltwater account.

To create a new tag in your account use the `POST /v3/tags` endpoint. The endpoint requires the name of the tag you'd like to create:

```shell
curl --request POST \
  --url https://api.meltwater.com/v3/tags \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json' \
  --data '{
  "tag": {
    "name": "My new tag"
  }
}'
```

If the tag is successfully created you will receive a `201` status code from the API, and a response including the ID of the newly created tag:

```json
{
  "tag": {
    "id": 123,
    "name": "My new tag"
  }
}
```

## Removing tags from your account

To remove tags in your account use the `DELETE /v3/tags/<tag id>` endpoint.

**Note that removing a tag from your account will also remove the tag from any documents with the tag.**

The endpoint requires the ID of the tag you'd like to remove as part of the URL:

```shell
curl --request DELETE \
  --url https://api.meltwater.com/v3/tags/123 \
  --header 'apikey: **********' \
  --header 'Content-Type: application/json'
```

If the tag is successfully removed from your account you will receive a `204` status code from the API.

---

## Chat Completion

# Mira API — Chat Completion

In this tutorial we'll get you up and running with the chat-completion features of the Mira API.

We do not cover here suggested prompts for potential use cases. Check out the [prompt library](https://app.meltwater.com/a/mira/prompts) in the Meltwater application for prompt ideas.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* Access to Mira API

## Chat completion endpoint

The API supports chat completion in both streaming and non-streaming mode through the `POST /v3/mira/chat` endpoint.

Parameters for the endpoint include:

* `user_prompt` - The prompt for completion e.g. "What were the top stories for Adidas last week?"
* `stream` - `true` for streaming mode, `false` for non-streaming mode
* `thread_id` - (optional) if not provided the request will start a new conversation thread; if provided the context of the existing thread you reference will be included as context for the chat completion
* `company_id` - (optional) Query parameter. The ID of the company to access. If not provided, your default company will be used. See [working with multiple companies](/guides/getting-started/multiple-companies) for more details.

## Non-streaming mode

For non-streaming chat completion, send a request to the `POST /v3/mira/chat` endpoint:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/chat" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "user_prompt": "What is going on in the news with fast fashion in the last 7 days?",
    "stream": false
}'
```

If the request is successful you will see a response similar to below, with the response content itself in [Markdown](https://www.markdownguide.org/):

```json
{
    "messages": [
        "1. **Shein Faces Backlash Amid Pop-Up Store Launch in Dijon**\n   - Summary: Shein's pop-up store in Dijon attracted hundreds of customers but also faced protests..."
    ],
    "thread_id": "684afd4a43dc9fef57f754cb"
}
```

*Currently only a single message will be returned in the `messages` field.*

The `thread_id` field returned allows you to continue the conversation. So for example, you could ask a follow-up question for more details:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/chat" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "user_prompt": "Which story had the highest reach?",
    "stream": false,
    "thread_id": "684afd4a43dc9fef57f754cb"
}'
```

Note that in non-streaming mode, the API will wait for up to 300 seconds for the chat response to be completed by the system. If the response exceeds 300 seconds the API will return a `504` status code and an error message.

## Streaming mode

For chat completion in streaming mode set the `stream` field to `true`:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/chat" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "user_prompt": "What is going on in the news with fast fashion in the last 7 days?",
    "stream": true
}'
```

The API will respond by streaming server-side events, similar to the following:

```
data: {"id":"chatcmpl-43d3c1b9-08a4-4613-b42e-544560628814","object":"chat.completion.chunk","created":1749745452,"choices":[{"index":0,"delta":{"role":"assistant","content":"Analy"}}]}

data: {"id":"chatcmpl-43d3c1b9-08a4-4613-b42e-544560628814","object":"chat.completion.chunk","created":1749745452,"choices":[{"index":0,"delta":{"content":"zing"}}]}

....

data: [DONE]
```

The `[DONE]` event can be used to detect when the response stream has been completed.

Note that for streaming mode the Thread ID is returned as a response header called `Thread-Id`.

## Rate limits

Calls are limited to 100 requests per minute.

---

## MCP Server

# Mira API — MCP Server

[MCP](https://modelcontextprotocol.io/introduction) is quickly becoming the recognised standard for integrating remote tools and resources into LLMs.

In this guide we'll explain the MCP Server integration option for the Mira API, by showing how you can integrate Mira with OpenAI.

*This guide is largely based on the [OpenAI Remote MCP guide](https://platform.openai.com/docs/guides/tools-remote-mcp). Please refer to the original guide for full details and code samples in other programming languages.*

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* Access to Mira API
* Access to Open AI, and your Open AI API token

## Meltwater API MCP Server Specification

The Meltwater API MCP Server exposes the following description and tools to LLMs:

```json
{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "tools": [
            {
                "annotations": {
                    "destructiveHint": false,
                    "openWorldHint": true,
                    "readOnlyHint": true
                },
                "description": "Ask Meltwater's MIRA assistant about stories, trends, and topics in news or social media.\n\nUse natural language queries like 'What were the top stories for Microsoft last week?' or 'How is climate change being discussed on social media?'\n\nAccess current news stories, social media trends, and emerging topics across global media sources.\nGet insights on brand sentiment, competitive analysis, and industry developments.\nUnderstand social media conversations, influencer discussions, and public opinion trends.\nAnalyze breaking news, story development, and media coverage patterns.",
                "inputSchema": {
                    "type": "object",
                    "required": [
                        "prompt"
                    ],
                    "properties": {
                        "project_id": {
                            "type": ["null", "string"],
                            "description": "Project ID to tailor the responses to a specific project's system prompt. (optional)"
                        },
                        "prompt": {
                            "type": "string",
                            "description": "Prompt to send to the conversational chat"
                        }
                    },
                    "additionalProperties": false
                },
                "name": "ask"
            },
            {
                "annotations": {
                    "destructiveHint": false,
                    "openWorldHint": true,
                    "readOnlyHint": true
                },
                "description": "Retrieve a list of Mira API projects with their associated ids.\n    \nThese project ids can be passed into the ask tool to tailor the responses to a specific project.",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "page": {
                            "type": ["null", "integer"],
                            "description": "Page number for the project list. Default is 1. (optional)"
                        },
                        "page_size": {
                            "type": ["null", "integer"],
                            "description": "Number of projects to return per page. Default is 100. (optional)"
                        },
                        "sort": {
                            "type": ["null", "string"],
                            "description": "Sort direction for the project list. Can be either asc or desc. Default is desc. (optional)"
                        }
                    },
                    "additionalProperties": false
                },
                "name": "list_projects"
            }
        ]
    }
}
```

Note the descriptions provided in the specification — these are critical to how an LLM will select the tools exposed, and how it will form prompts when calling those tools.

## Specifying an MCP Server in OpenAI

The OpenAI Responses API uses the following structure to reference remote MCP servers:

```json
{
    "type": "mcp",
    "server_label": "meltwater-api",
    "server_url": "https://api.meltwater.com/mcp",
    "require_approval": "never",
    "headers": {
        "apikey": "<YOUR MELTWATER API KEY>"
    }
}
```

Here the critical fields are:

* `server_url`: The URL for the Meltwater MCP server.
* `apikey`: Your Meltwater API key, which will be sent as a header in requests to the server by OpenAI.

## Calling the Responses API

Using the MCP approach, it's incredibly simple to call the Responses API including the MCP server tools.

This example code calls the Responses API, and provides a simple prompt for a news brief. Because of the description provided by the Meltwater MCP server, the LLM should know to direct questions regarding news and social insights to the Mira API.

```python
from openai import OpenAI

client = OpenAI(api_key="<YOUR OPENAI API KEY>")

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "meltwater-api",
            "server_url": "https://api.meltwater.com/mcp",
            "require_approval": "never",
            "headers": {
                "apikey": "<YOUR MELTWATER API KEY>"
              }
        },
    ],
    input="What is going on in the news with fast fashion in the last 7 days?",
)

print(resp.output_text)
```

The output from the Responses API call will be returned in Markdown format.

For fuller examples and explanation of the Responses API, see the [official documentation](https://platform.openai.com/docs/guides/tools-remote-mcp).

## Integrating with Claude Desktop

You can also configure Claude Desktop to use the Meltwater MCP server directly. This allows you to chat with Claude and have it automatically access Meltwater's news and social media insights.

### Configuration

To configure the MCP server, you need to edit the `claude_desktop_config.json` file:

**File Location:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

You can also access this file through Claude Desktop by going to Settings > Developer > Edit Config.

Add the following configuration to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "meltwater": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.meltwater.com/mcp",
        "--header",
        "apikey: ${MELTWATER_API_KEY}"
      ],
      "env": {
        "MELTWATER_API_KEY": "<your api key>"
      }
    }
  }
}
```

**Configuration Details:**
- `meltwater`: A unique identifier for this MCP server
- `command`: Uses `npx` to run the `mcp-remote` package
- `args`: Specifies the server URL and authentication header
- `env`: Environment variables, including your Meltwater API key

**Setup Steps:**
1. Replace `<your api key>` with your actual Meltwater API key
2. Save the configuration file
3. Restart Claude Desktop
4. The Meltwater MCP server will now be available in your Claude conversations

Once configured, you can ask Claude questions about news and social media trends, and it will automatically use the Meltwater API to provide current insights.

## Limits

### Rate limits

The Meltwater MCP server is limited to **60 requests per minute**. This limit is shared with the [Mira API Responses endpoint](/guides/mira-api/responses).

### Conversation size

Conversations with Mira can contain up to **290,000 tokens** of message history. If a conversation exceeds this limit, the most recent messages are retained. See the [Mira API Responses documentation](/guides/mira-api/responses#limits) for more details.

---

## Overview(Mira-api)

# Mira API

In this guide we'll introduce you to the Mira API. This API allows you to integrate AI-based insights and outcomes into your solutions.

:::info Can I access the Mira API?
The Mira API is sold as a separate package to the standard Meltwater API, so check your contract to see if you have access. If you are interested in gaining trial access to the API please talk to your account manager, or our sales team.
:::

## Meltwater platform

The **Meltwater platform** ingests and enriches data from a wide variety of sources, including news and social platforms. Data is enriched by a set of enrichments (sentiment, language, key phrases, etc.) and stored in a consistent data schema.

This vast data set is now being used to provide our customers with Gen-AI powered insights and outcomes within our application suite. Using AI technology we can now provide overviews of news coverage, themes in trending social posts, generate high quality reports — in fact the list of possibilities is growing by the day.

## Mira API

The Mira API exposes AI features from within the Meltwater suite to API customers.

For example [Mira Studio](https://www.meltwater.com/en/ai) is our AI assistant within our suite. Through a chat interface users can ask for a wide range of news and social insights, and can ask for assistance creating reports, and many other tasks.

### Responses Endpoint

The **responses** endpoint is our chat-completion endpoint.

The endpoint supports streaming and non-streaming modes, one or multiple input messages, and returns citations for responses.

It is designed for integration with AI assistants and agents.

Take a look at the [Responses](/guides/mira-api/responses) guide for more details.

### MCP Server

The Mira API is now exposed as a [remote MCP server](https://modelcontextprotocol.io/introduction) for ease-of-integration.

Read our [MCP Server guide](/guides/mira-api/mcp-server) to learn about this integration approach.

---

## Projects

# Mira API — Projects

In this guide we'll explain how you can get started with Mira Projects when using the Mira API. Mira Projects allow you to ground Mira API responses with top level instructions, and Meltwater assets.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* Access to Mira API

## Listing projects

The API provides access to your available projects through the `GET /v3/mira/projects` endpoint.

*Note that this response will list the projects accessible to the user you have associated with your API key.*

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/mira/projects" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

Example response:

```json
{
  "projects": [
    {
      "id": "proj-123456789",
      "name": "Brand Monitoring Q1 2024",
      "share_level": "user",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-03-20T14:45:00Z"
    },
    {
      "id": "proj-987654321",
      "name": "Competitor Analysis",
      "share_level": "company",
      "created_at": "2024-02-01T09:15:00Z",
      "updated_at": "2024-03-18T16:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_items": 25,
    "total_pages": 3
  }
}
```

## Pagination

The projects endpoint supports pagination with the following query parameters:

* `page` - Page number (default: 1, minimum: 1)
* `page_size` - Items per page (default: 10, minimum: 1, maximum: 100)
* `sort` - Sort order: `asc` or `desc` (default: `desc`)
* `company_id` - (optional) The ID of the company to access. If not provided, your default company will be used. See [working with multiple companies](/guides/getting-started/multiple-companies) for more details.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/mira/projects?page=2&page_size=20&sort=asc" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

## Project properties

Each project includes the following properties:

* `id` - Unique project identifier
* `name` - Human-readable project name
* `share_level` - Access level (`user`, `company`, `workspace`)
* `created_at` - ISO 8601 timestamp of project creation
* `updated_at` - ISO 8601 timestamp of last project update

## Using projects for Mira requests

You can associate a project with your responses endpoint requests by including the project ID in the `Project-ID` header:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/responses" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --header "Project-ID: proj-123456789" \
  --data '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What are the latest trends in sustainable fashion?"
          }
        ]
      }
    ],
    "stream": false
  }'
```

---

## Responses

# Mira API — Responses

In this tutorial we'll get you up and running with the responses feature of the Mira API.

The responses endpoint provides advanced chat completion capabilities with support for multiple input messages and enhanced context handling. It is our recommended approach for integration with AI assistants and agents.

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* Access to Mira API

## Responses endpoint

The API supports advanced chat completion through the `POST /v3/mira/responses` endpoint. This endpoint allows you to send multiple input messages and supports both streaming and non-streaming modes.

Body parameters for the endpoint include:

* `input` - Array of input messages with role and content
* `stream` - `true` for streaming mode, `false` for non-streaming mode

Supported headers include:

* `Thread-ID` - (optional) if provided, uses the existing thread; otherwise creates a new thread
* `Project-ID` - (optional) if provided, uses the specified Mira project for grounding responses

Query string parameters include:

* `company_id` - (optional) The ID of the company to access. If not provided, your default company will be used. See [working with multiple companies](/guides/getting-started/multiple-companies) for more details.

## Input message format

Each input message should have:

* `role` - The role of the message sender (e.g., "user", "assistant")
* `content` - Array of content items, each with:
  * `type` - Content type ("text")
  * `text` - The actual text content

## Non-streaming mode

For non-streaming responses, send a request to the `POST /v3/mira/responses` endpoint:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/responses" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What are the latest trends in sustainable fashion?"
          }
        ]
      }
    ],
    "stream": false
  }'
```

Example response:

```json
{
  "id": "resp-684afd4a43dc9fef57f754cb",
  "object": "response",
  "created": 1749745452,
  "output": [
    {
      "id": "msg-123",
      "role": "assistant",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "text",
          "text": "Based on recent industry analysis, here are the key sustainable fashion trends:\n\n1. **Circular Fashion Models** - Brands are increasingly adopting circular economy principles...",
          "annotations": [
            {
              "news_document_citation": {
                "citation_id": "cite-1",
                "citation_type": "news",
                "id": "doc-123",
                "title": "Sustainable Fashion Report 2024",
                "url": "https://example.com/article",
                "source_name": "Fashion Weekly",
                "publish_date": "2024-01-15",
                "content": "Industry report on sustainable fashion trends...",
                "rank": 1,
                "reach": 50000,
                "engagement": 1200,
                "sentiment": "positive"
              }
            }
          ]
        }
      ]
    }
  ],
  "output_text": "Based on recent industry analysis, here are the key sustainable fashion trends..."
}
```

## Streaming mode

For streaming responses, set the `stream` field to `true`:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/responses" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What are the latest trends in sustainable fashion?"
          }
        ]
      }
    ],
    "stream": true
  }'
```

The API will respond with server-sent events containing incremental updates to the response.

## Multi-message conversations

The responses endpoint allows you to manage your own conversation history (and provide relevant messages to Mira as a set of input messages), or alternatively Mira can maintain a conversation thread for you.

If you'd like Mira to answer based upon an ongoing thread managed by Mira you can use the optional `Thread-ID` header. Start a conversation by providing an input message and no `Thread-ID` header. Mira will then give a response including a `Thread-ID` response header for the new conversation. Return this `Thread-ID` header in follow up calls to have Mira use this thread context for answers.

When managing conversation state yourself, you don't need to use the `Thread-ID` header since you're providing the complete conversation context.

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/mira/responses" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What are the latest trends in sustainable fashion?"
          }
        ]
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "The main trends include circular fashion, eco-friendly materials, and transparency in supply chains."
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Can you provide specific examples of brands implementing these trends?"
          }
        ]
      }
    ],
    "stream": false
  }'
```

## Limits

### Rate limits

The Mira API is limited to **60 requests per minute**. This limit is shared across both the Responses endpoint and the [MCP server](/guides/mira-api/mcp-server).

### Conversation size

Conversations with Mira can contain up to **290,000 tokens** of message history. This includes all messages in the thread — both your prompts and Mira's responses.

For most use cases, this limit provides ample room for extended conversations. If a conversation exceeds this limit, Mira will automatically retain the most recent messages to ensure the conversation can continue, while older messages may no longer be referenced in responses.

## Citations and annotations

Annotations provide additional context for responses from the Mira API. Currently the API only supports document citations. Document citations give you visibility into the documents considered by Mira when providing its answer to your prompt.

Citations can be matched to the output text from Mira based upon the following syntax: `[^(citation_id)]`. For example if the output text contains `[^3]` then this is referring to the annotation with `citation_id` of `3` in the annotations list.

For non-streaming mode, annotations are returned in the response payload under the path `output.content.annotations`.

For streaming mode, annotations are returned in response events under the path `item.content.annotations`. The following events can contain annotations:
* `response.completed`

Note that citations below are illustrative. Title and content are included when possible, depending on compliance rules the system needs to apply for sources. Depending on the data source for citation, different metrics will be available or not.

### News document citations

Citations with `citation_type` of `news_document_citation` are references to news articles considered by Mira in its response.

```json
{
  "news_document_citation": {
    "citation_type": "news_document_citation",
    "citation_id": "14",
    "id": "M7VJ0_BNa4jkk5PKzHdl_H2ByqY",
    "url": "https://...",
    "title": "Adidas Football...",
    "content": "Today it was announced that...",
    "source_name": "News Site",
    "reach": 9504359,
    "engagement": 39,
    "social_echo": 39,
    "outlet_types": [
      "television"
    ],
    "views": 20927
  }
}
```

### Social document citations

Citations with `citation_type` of `social_document_citation` are references to social posts considered by Mira in its response.

```json
{
  "social_document_citation": {
    "citation_type": "social_document_citation",
    "citation_id": "13",
    "id": "1757417640000_g8hdUz_RK8HxrjK2OfyxKqLlkW8A",
    "title": "Adidas Football...",
    "url": "https://...",
    "content": "Today I read that....",
    "platform": "facebook",
    "author": "fb_user",
    "publish_date": "2025-09-09T11:34:33.563000Z"
  }
}
```

### Generic document citations

Citations with `citation_type` of `other_document_citation` are references to documents other than news articles and social posts.

```json
{
  "other_document_citation": {
    "citation_type": "other_document_citation",
    "citation_id": "14",
    "id": "M7VJ0_BNa4jkk5PKzHdl_H2ByqY",
    "title": "Adidas Football...",
    "url": "https://...",
    "content": "Today I read that....",
    "views": 20927
  }
}
```

---

## Overview(Social-analytics)

# Social Analytics — Overview

In this guide we'll introduce you to key Social Analytics concepts of the Meltwater API and platform.

## Meltwater platform

The **Meltwater platform** ingests and enriches data from a wide variety of sources, including news and social platforms. Data is enriched by a set of enrichments (sentiment, language, key phrases, etc.) and stored in a consistent data schema.

Private data, such as data from owned social connections is held privately for each customer. The Meltwater application accesses this data to provide application features. The Meltwater API is built upon the same platform and data stores.

**Social Analytics** features of the API allow you to fetch and analyse content and posts on social networks for accounts that you have connected to the Meltwater platform. If you are using one of our [BI connectors](/guides/integrations/overview), this is calling the API behind the scenes for you, using your API credentials.

**Owned Social** data is content and posts related to 'owned' social accounts that you own and have connected to the Meltwater platform. For example, if you connect your owned Facebook account to Meltwater, using the API you can access analytics and posts for this account. This is a subset of Social Analytics, which also includes paid social data, currently not available in the API.

Broadly speaking you can access the same data through the API as a user sees in the application. However, due to social network terms we cannot provide every network and data point in the API.

## Sources

When using the API for owned social features you will often be asked for a source. A source in this case is the social network you'd like data for, for example Facebook or Instagram. Use the API name in the `source` field of your requests.

| Social network | API name |
|---|---|
| Facebook | `facebook` |
| Instagram | `instagram` |
| LinkedIn | `linkedin` |
| TikTok | `tiktok` |
| X | `twitter` |

Not every metric or dimension is available for every source. See the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page for per-source coverage of analytics metrics and dimensions.

## Connections

In the Meltwater application you configure a connection to bring data from a social network account into the platform.

Read more about how to set up social connections in our [help portal](https://community.meltwater.com/engage-setup-45/grouping-your-owned-social-accounts-in-meltwater-social-connections-owned-tab-7704). You can view your owned social connections in the [Meltwater application](https://app.meltwater.com/settings/social-connections/private).

## Accounts

A social network account, for example on Facebook, for which you provide your credentials in a connection.

Once you've connected an account to the Meltwater platform data for that account will be fetched periodically using the credentials you provided.

## Fetching Owned Posts and Analytics

The API provides endpoints for retrieving analytics and posts for your connected accounts:

- [Fetching Owned Analytics & Posts](/guides/social-analytics/v3/fetching-owned-analytics-and-posts) — walk through retrieving performance metrics and posts from your connected accounts

The metrics available from the API are documented on the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page.

---

## Fetching Owned Analytics & Posts


In this tutorial we'll cover the basics of accessing owned social analytics and posts using the API.

**Note that you need access to the Meltwater API, plus Engage or Social Analytics features in the Meltwater application to use these features.**

## Before you start

To run through this tutorial, you will need:

* Your Meltwater API token
* An [owned social connection](https://community.meltwater.com/engage-setup-45/grouping-your-owned-social-accounts-in-meltwater-social-connections-owned-tab-7704) configured for your Meltwater account

## Fetching your connected accounts

When calling the API to fetch owned social analytics you must provide the account IDs you would like data for.

You can fetch your list of accounts by calling the `GET /v3/owned/accounts` endpoint:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "count": 10,
    "accounts": [
        {
            "id": "12345678945687853",
            "name": "My Facebook account",
            "logo": "http://...",
            "source": "facebook"
        },
        {
            "id": "12345678945687234",
            "name": "My Instagram account",
            "logo": "http://...",
            "source": "instagram",
            "username": "my_instagram_account"
        },
        {
            "id": "urn:li:organization:12522",
            "name": "My LinkedIn account",
            "logo": "http://...",
            "source": "linkedin",
            "username": ""
        }
    ] 
}
```

Here you are fetching the accounts that you have set up owned connections for in the Meltwater application. For each account you'll see an `id`, which you'll use in the `account_ids` parameter when fetching metrics and analytics.

All your connections are returned in this one call, regardless of the social network the connection is for.

**Note that for LinkedIn, the ID of accounts is in the form `urn:li:organization:<id>`. You need to pass this entire string as the account ID when requesting posts and metrics.**

## Fetching posts

You can use the API to fetch the top posts for owned social accounts. You might do this to report the most engaged with posts in a period of time for example.

When calling the API you can fetch multiple posts for multiple accounts in one API call. Note the accounts must be from the same social network.

You can fetch posts by calling the `GET /v3/owned/accounts/posts/top_posts` endpoint.

When fetching posts you must provide the following parameters:

- `source`: The social network of the accounts you are requesting (for example `facebook`)
- `account_ids`: One or more IDs of accounts you'd like posts for (up to 10 accounts), as a comma-separated list
- `start`: The start of the time period (inclusive)
- `end`: The end of the time period (inclusive)

Optionally you can also provide any of the following parameters:

- `post_types`: The types of the post you'd like to fetch, for example `status`, as a comma-separated list
- `sort_by`: The field to sort posts by, defaults to `created_at`
- `sort_order`: The direction of the sort applied, defaults to `desc`
- `page_size`: The number of posts to return per page, defaults to `10`, maximum of `100`
- `page`: The page number to return, defaults to `1`

:::info Sort order options
We aim to make features consistent across social networks, but as each network has different names for their concepts and metrics the sort order options differ per network for the Top Posts endpoint.

Sort orders of `engagement_rate` and `created_at` are supported for all networks.

In addition we support the following sort order options for each network:

- Facebook: `comments_count`, `reactions_count`, `shares_count`
- Instagram: `comments_count`
- LinkedIn: `comment_count`
- TikTok: `comments`
:::

For example this call would fetch the top posts sorted by descending `engagement_rate`, for a single Facebook account, for the first week of December 2021:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/posts/top_posts?source=facebook&account_ids=12345678945687853&start=2021-12-06&end=2021-12-12" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "count": 9,
    "page": 1,
    "page_size": 10,
    "posts": [
        {
            "post_id": "12345678945687853_4619537758143245",
            "post_type": "status",
            "url": "https://www.facebook.com/12345678945687853/posts/4619537758143245/",
            "content": "Example post content",
            "media_url": "",
            "tags": [
                "My Tag",
                "My Other Tag"
            ],
            "metrics": {
                "comments_count": 3,
                "post_impressions_organic_unique": 6
            },
            "account": {
                "source": "facebook",
                "id": "12345678945687853",
                "name": "My Facebook Account"
            },
            "created_at": "2021-12-07T17:50:01+0000"
        }
    ]
}
```

The `count` field in the response tells you how many posts are available for the accounts in the timeframe.

For each post the API returns:

- The ID, type and URL for the post
- When the post was created
- The account which the post belongs to
- All available metrics for the post

*Note that the post metrics available will vary by social network. These are documented on the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page.*

### Filtering using Tags

The `top_posts` endpoint allows you to filter results based on tags users have applied to posts in the Meltwater application. For instance users may tag posts for a particular campaign.

To filter results to specific tags use the following parameters:

- `tag`: The tag(s) to filter to. You can provide multiple values.
- `match_all_tags`: Set to `true` if you want posts to match all tags you provide, or `false` to match one or more of your tags. (Defaults to `false`.)

```shell
curl -X GET \
--url "https://api.meltwater.com/v3/owned/accounts/posts/top_posts?source=facebook&account_ids=12345678945687853&start=2021-12-06&end=2021-12-12&tag=MyTag&tag=MyOtherTag" \
--header "Accept: application/json" \
--header "apikey: **********"
```

## Fetching numeric account metrics

The API supports a number of account-level metrics. You can fetch these metrics to report the performance of your owned social accounts.

First we'll look at 'numeric' metrics (basic metrics like the number of page fans), then we'll look at demographic metrics and analytics.

### Understanding which metrics are available

The metrics available for each of your accounts depends on the social network they belong to, currently supported networks include:

- Facebook
- Instagram
- LinkedIn
- X
- TikTok

As we expect this list to grow over time, we provide a full list of metrics per network on the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page. Metrics are listed by source, then whether they are account-level or post-level, and finally by type.

You can also call the `GET /v3/owned/supported_metrics` endpoint to programmatically fetch the list of supported metrics.

### Making an API call

You can fetch numeric account metrics by calling the `GET /v3/owned/accounts/metrics/numeric` endpoint.

*Note this endpoint only supports `int` and `float` account metrics. There are separate endpoints for `breakdown`, `nested-breakdown` and `heatmap` typed account metrics.*

When fetching account metrics you provide the following parameters:

- `source`: The social network of the accounts you are requesting (for example `facebook`)
- `account_ids`: One or more IDs of accounts you'd like metrics for (up to 10 accounts), as a comma-separated list
- `start`: The start of the time period (inclusive)
- `end`: The end of the time period (inclusive)
- `metrics`: One or more metrics you'd like fetched (up to 10 metrics), as a comma-separated list

For example this call would fetch the `page_fans` metric for a single Facebook account, for the first week of December 2021:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/numeric?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=page_fans" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "daily_values": [
                {
                    "date": "2021-12-06",
                    "page_fans": 350
                }
            ]
        }
    ]
}
```

In the response the API returns for each account requested, for each date in the requested time period, a daily value for each requested metric.

*Note you can request multiple metrics for multiple accounts in one API call, but the accounts must be from the same social network.*

## Fetching demographic analytics

In addition to simple numeric account metrics, the API also allows you to fetch demographic-breakdowns of account fans and followers.

The endpoint you need to call for a particular breakdown will depend on the metric's type, as listed on the [Owned Social Analytics Options](/api-reference/analytics-options/owned-social) page. For example the `demographics_audience_city` metric is of type `breakdown`, so you would call the `GET /v3/owned/accounts/metrics/breakdown` endpoint.

All of the metrics endpoints require the same parameters:

- `source`: The social network of the accounts you are requesting
- `account_ids`: One or more IDs of accounts you'd like metrics for (up to 10 accounts), as a comma-separated list
- `start`: The start of the time period (inclusive)
- `end`: The end of the time period (inclusive)
- `metrics`: One or more metrics you'd like fetched (up to 10 metrics), as a comma-separated list

### Fetching breakdown metrics

A 'breakdown' metric is an analysis that provides a single-level breakdown by a category or concept. For example, the `demographics_audience_country` metric breaks down the audience for a Facebook page by country.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/breakdown?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=demographics_audience_country" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "demographics_audience_country": [
                        {
                            "key": "NO",
                            "key_label": "Norway",
                            "value": 591
                        }
                    ]
                }
            ]
        }
    ]
}
```

### Fetching nested-breakdown metrics

A 'nested-breakdown' metric is an analysis that provides a double-level breakdown by two categories or concepts. For example, the `demographics_gender_age` metric breaks down the audience for a Facebook page by firstly gender, then age group.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/nested_breakdown?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=demographics_gender_age" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "demographics_gender_age": [
                        {
                            "key": "male",
                            "subkey": "55-64",
                            "value": 591
                        }
                    ]
                }
            ]
        }
    ]
}
```

### Fetching heatmap metrics

A 'heatmap' metric is an analysis that provides a breakdown over date and time. For example, the `page_fans_heatmap` metric breaks down the audience for a Facebook page by how active they are each day and hour.

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/owned/accounts/metrics/heatmap?source=facebook&account_ids=12345678945687&start=2021-12-06&end=2021-12-12&metrics=page_fans_heatmap" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

The response will be similar to the following:

```json
{
    "accounts": [
        {
            "source": "facebook",
            "id": "12345678945687",
            "name": "My Facebook Account",
            "username": "",
            "daily_values": [
                {
                    "date": "2022-01-28",
                    "page_fans_heatmap": [
                        {
                            "hour": 0,
                            "value": 9212
                        }
                    ]
                }
            ]
        }
    ]
}
```

In this case, for each day in the requested range, the API returns an hourly value for the metric. Note that the time is always in PST timezone.

---

## API Changes 2023

# Preparing for upcoming API changes in April 2023

This guide explains how you can prepare your integration to be ready for changes to the Meltwater API that were scheduled for 3rd April 2023.

Please note that you only need to read this guide and consider changes if:

* You create or fetch results of exports programmatically using the Meltwater API
* You create, modify, list or fetch Saved Searches programmatically using the Meltwater API

If you have any questions regarding these changes please contact our [support team](/help/support).

## Breaking changes to the API

On 3rd April 2023, we made breaking changes to the API which impacted customers creating exports and creating/updating Saved Searches using the API.

At a high level the following changes were made:

* When creating exports using the API you need to specify the format of the result you would like.
* All Saved Searches were migrated to Explore category searches, and you can no longer create or update MI category searches.

## Export format changes

### Creating exports

When creating an export you must include a `format` parameter. This parameter supports `CSV` or `JSON` as valid values.

For example, when creating a one-time export:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/exports/one-time" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "onetime_export": {
    "search_ids": [<search_id>],
    "start_date": "2018-09-01T01:00:00",
    "end_date": "2018-10-01T01:00:00",
    "format": "JSON"
  }
}'
```

Or, when creating a recurring export:

```shell
curl -X POST \
  --url "https://api.meltwater.com/v3/exports/recurring" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "apikey: **********" \
  --data '{
  "recurring_export": {
    "search_ids": [<search_id>],
    "window_time_unit": "DAY",
    "window_time": "09:00:00",
    "window_size": 7,
    "timezone": "Etc/UTC",
    "format": "JSON"
  }
}'
```

If you create an export without specifying a format, the result will be output in JSON format.

### Fetching export results

When you provide a value for the `format` field when creating an export, the `data_url` field for your export will be the full URL to the export result. If you previously added a format parameter to the data URL, you no longer need to do so.

### Recurring exports already running

For any recurring exports where you need the output in CSV format, you will need to stop and restart any recurring exports you have running, specifying the `format` parameter. For any exports that remain running with no format specified, the API will output data in JSON format going forward.

## Saved Search changes

At Meltwater we simplified Saved Searches. Previously both legacy MI category searches and Explore category searches were supported. Now only Explore category searches are supported.

### What happened to existing searches?

On 3rd April 2023, all searches of MI category were automatically converted to Explore category searches. The results you receive from exports, streaming and analytics features were not changed because the `type` of your MI search, and any `source selection` set, were applied as a filter to the migrated Explore search.

### What changed in the API?

The following fields are no longer returned by the API and can no longer be specified when creating or updating searches:

* `type` and `category` fields
* `search_id` field (duplicated `id`)
* `source_selection_id` field

The `GET source_selections` endpoint was also removed.

### Updated API examples

**Listing Saved Searches:**

```json
{
  "searches": [
    {
      "updated": "2021-12-16T15:28:47Z",
      "id": 123456,
      "name": "Tesla",
      "query": {
        "filter_set": null,
        "case_sensitivity": "no",
        "not_keywords": [],
        "any_keywords": [],
        "all_keywords": ["tesla"],
        "type": "keyword"
      }
    }
  ]
}
```

**Creating a Saved Search:**

```shell
curl -X POST \
  --url "https://api.meltwater.net/v3/searches" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence\")",
              "type": "boolean"
          }
      }
  }'
```

**Updating a Saved Search:**

```shell
curl -X PUT \
  --url "https://api.meltwater.net/v3/searches/12345" \
  --header 'Content-Type: application/json' \
  --header "apikey: **********" \
  --data-raw '{
      "search": {
          "name": "Example search - updated",
          "query": {
              "case_sensitivity": "no",
              "boolean": "(\"business intelligence tools\")",
              "type": "boolean"
          }
      }
  }'
```

## FAQ

**How can I tell if my search has been migrated?**

You will see that source selections have been replaced with filter sets in your migrated searches. The `updated_at` fields will have been updated also. Searches previously categorised as Explore will be left unaltered.

**Do I still provide the Source Selection ID when updating a MI search?**

Source selections have been deprecated in the API and this field should no longer be given when creating/updating a search. Migrated searches will have a corresponding filter set applied to them to match the prior selected sources.

**What happens to my Explore searches?**

The migration is focused on converting legacy MI searches to Explore. Behind the scenes, Explore searches are unaffected by the migration. The only change is that we no longer indicate that the search is Explore in API responses.

**Do I need to recreate my recurring exports?**

The Explore to MI migration will not affect your exports, there is no need to recreate them. The only reason you would need to recreate your recurring exports is if you require a CSV output over the default JSON.

---

## Changelog


On this page we inform you about changes to the Meltwater API.

---

### 7 April 2026 — Bring Your Own Content (BYOC) - New origin platform added - Telegram

The BYOC API now supports `telegram` as an origin platform. You can submit documents with `originPlatform: "telegram"` and the following content types: post, comment, reply, repost, quoted.

---

### 3 March 2026 — Usage statistics per API token

The [Usage Data page](/guides/getting-started/accessing-usage-statistics) in the Meltwater application now shows usage broken down by API token. Use the token selector dropdown at the top of the page to view usage for a specific token.

Additionally, the `GET usage/me/metrics/{metric}` and `GET usage/me/requests` API endpoints now accept an optional `token_id` query parameter to filter usage by API token.

---

### 12 January 2026 — Bring Your Own Content (BYOC) - Adding duplicate detection and monitoring imported data

We've added support for duplicate detection when importing documents via the BYOC API for TikTok. This feature helps prevent the ingestion of duplicate content by checking for existing documents with the same unique identifiers before adding new entries.

For more information please read the [BYOC Monitoring Imported Data](/guides/bring-your-own-content/monitoring-imported-data) guide.

---

### 26 November 2025 — Bring Your Own Content (BYOC) - New field added - user.imageUrl

We have expanded the BYOC API schema to include a new optional field `user.imageUrl` in the document payload. This field allows you to specify a URL for the user's profile image associated with the document being submitted.

---

### 13 November 2025 — Bring Your Own Content (BYOC) - Explore+ Custom Fields

We have added support for **custom fields** in the Bring Your Own Content (BYOC) API when using **Explore+**. This enhancement allows you to attach additional metadata to your documents, enabling more granular categorisation and analysis within **Explore+**.

For more information, see the [Explore+ Custom Fields](/guides/bring-your-own-content/custom-fields-management) guide.

---

### 30 September 2025 — Bring Your Own Content (BYOC) - Frequently Asked Questions

We have compiled a collection of the most [frequently asked questions](/help/faqs) about the Bring Your Own Content (BYOC) API.

---

### 22 September 2025 — Bring Your Own Content (BYOC) - unique id within a batch

Starting now, the `id` field must be unique within each batch of submitted documents. If duplicate IDs are detected, the entire batch will be rejected with a `400 Bad Request` error.

This change improves the reliability of import progress tracking and makes it easier to spot unintended duplicates.

---

### 9 September 2025 — Bring Your Own Content (BYOC) - data monitoring

We've added support for monitoring imported documents and their progress.

For more information please read the [BYOC Monitoring Imported Data](/guides/bring-your-own-content/monitoring-imported-data) guide.

---

### 8 September 2025 — Bring Your Own Content (BYOC) - data management

We've added support for deleting imported documents and updated the documentation on how to reliably identify documents for updates and deletions.

For more information please read the [BYOC Managing Imported Data](/guides/bring-your-own-content/managing-imported-data) guide.

---

### 13 August 2025 — Bring Your Own Content (BYOC) - batch size increased to 500

We have increased the batch size for the Bring Your Own Content (BYOC) API to 500 documents per request. This allows you to upload larger batches of your own content more efficiently, reducing the number of API calls needed for bulk uploads.

---

### 1 August 2025 — Bring Your Own Content (BYOC) API now available

You can now bring your own content into the Meltwater platform using the new Bring Your Own Content (BYOC) API. This feature allows you to seamlessly integrate your own data with Meltwater's native data sources, enabling consistent enrichment, analytics, and discovery across all Meltwater products.

For more information please read the [Bring Your Own Content API overview](/guides/bring-your-own-content/overview).

---

### 1 July 2025 — Explore+ API now available

The Explore+ API is now available, providing access to Explore+ assets and analytics through the Meltwater API.

---

### 26 June 2025 — Search Earned Media Documents

You can now search earned media documents using the Meltwater API, allowing you to fetch individual mentions matching your searches and filters.

---

### 23 April 2025 — Tagging Earned Media Documents

You can now manage tags on earned media documents using the Meltwater API.

---

### 31 March 2025 — Applying Custom Categories to API Exports

You can now apply custom categories to your API exports.

---

### 21 October 2024 — Facebook deprecated metrics

Several Facebook metrics have been deprecated and are no longer available through the API.

---

### 25 July 2024 — Custom Earned Analytics - BETA

Custom earned media analytics are now available in BETA, allowing you to build more flexible analytics queries.

---

### 31 May 2024 — Tag filtering on Owned Social

You can now filter owned social posts by tags when using the top posts endpoint.

---

### 9 May 2024 — Additional Earned Media analytics options

Additional dimensions and measures are now available for earned media analytics.

---

### 25 April 2024 — New output templates for export and streaming

New output templates are now available for export and streaming responses.

---

### 3 January 2024 — Improved Combined Search Management

Improvements have been made to combined search management, including the ability to expand combined searches.

---

### 5 December 2023 — Omnichannel analytics

Omnichannel analytics are now available, allowing you to analyse data across multiple channels.

---

### 31 October 2023 — Enhanced Owned Social API with Additional Sources and Metrics

The Owned Social API has been enhanced with additional sources and metrics.

---

### 26 October 2023 — Sampling on the Export API

Sampling is now available on the Export API, allowing you to work with representative subsets of your data.

---

### 28 July 2023 — New sources, Kakaotalk and LineVoom added to the Meltwater API

Kakaotalk and LineVoom are now available as sources for exports, analytics, and streaming.

---

### 9 June 2023 — Notification of Support Link Change

The Meltwater support link has been updated.

---

### 3 April 2023 — Notification of Completed Migration

The migration of MI category searches to Explore category searches is now complete. See the [API Changes 2023 guide](/help/api-changes-2023) for more details.

---

### 8 March 2023 — Exports - Views data returned in export results

Views data is now returned in export results.

---

### 12 January 2023 — Notification of upcoming breaking changes

Notification of breaking changes scheduled for 3rd April 2023. See the [API Changes 2023 guide](/help/api-changes-2023) for full details.

---

### 18 March 2022 — Improved Language Detection

Language detection has been improved across all content types.

---

### 25 February 2022 — New Owned Social Analytics features

New owned social analytics features have been added, including additional metrics and analysis types.

---

### 4 November 2021 — Changes to YouTube data availability

Changes have been made to the availability of YouTube data in line with compliance requirements.

---

### 4 November 2021 — API credentials are now managed in the Meltwater application

API credentials can now be managed directly in the Meltwater application.

---

### 21 October 2021 — Exports - New document hashtags field

A new `document_hashtags` field has been added to export results.

---

### 23 September 2021 — Changes to accessing usage statistics

Changes have been made to how usage statistics can be accessed via the API.

---

### 17 September 2021 — Support for creating and updating Explore category searches

Full support for creating and updating Explore category searches is now available.

---

### 7 September 2021 — New source Little Red Book has been added to the Meltwater API

Little Red Book (Xiaohongshu) is now available as a source for exports, analytics, and streaming.

---

### 31 August 2021 — New sources, Douyin and WeChat added to the Exports API

Douyin and WeChat are now available as sources for exports.

---

### 20 August 2021 — New sources, Douyin and WeChat added to the Meltwater Analytics API

Douyin and WeChat are now available as sources for analytics.

---

### 10 August 2021 — New sources, Twitch, TikTok and Pinterest added to the Meltwater API

Twitch, TikTok and Pinterest are now available as sources across exports, analytics, and streaming.

---

### 7 July 2021 — Opening Text for Facebook and Instagram sources

Opening text is now available for Facebook and Instagram content.

---

### 8 February 2021 — Support for Facebook and Instagram in exports and analytics

Facebook and Instagram are now available as sources for exports and analytics.

---

### 1 February 2021 — Analytics - Expanding top languages and top country codes

The top languages and top country codes analytics endpoints now support a broader range of language codes and countries.

---

### 4 December 2020 — Exports - Additional fields for export results

Additional fields have been added to export results.

---

### 13 November 2020 — Analytics API - Multi-company support and Author Count Analysis

Multi-company support and Author Count analysis are now available in the Analytics API.

---

### 2 November 2020 — New analytics endpoints - top keyphrases, top locations, top entities

New analytics endpoints are now available for top keyphrases, top locations, and top entities analysis.

---

### 21 September 2020 — Upcoming changes to Twitter & YouTube data

Notification of upcoming changes to Twitter and YouTube data fields. See the [Compliance Changes](/help/compliance) page for full details.

---

### 7 September 2020 — Announcing API version 3

Announcing the launch of Meltwater API version 3, consolidating the Export API and Analytics API into a single consistent API. See the [Migration to V3 guide](/help/migration-to-v3) for details.

---

### 27 February 2020 — Removing data_url for INCOMPLETE one-time exports

The `data_url` field is no longer returned for `INCOMPLETE` one-time exports.

---

### 12 December 2019 — Adding Social Echo for Reddit

Social Echo is now available for Reddit documents.

---

### 26 November 2019 — Searches from Explore now fully available in the Export API

Searches created in the Explore interface are now fully available for use with the Export API.

---

### 12 November 2019 — Adding new reach fields to editorial documents

New reach fields have been added to editorial (news) documents.

---

### 20 September 2019 — Removing country from /companies endpoint

The `country` field has been removed from the `/companies` endpoint.

---

### 11 February 2019 — Simplified setup for exports based on tags

The setup process for creating exports based on tags has been simplified.

---

### 9 January 2019 — Added two fields `document_earned_traffic` and `document_hidden`

Two new fields have been added to export results: `document_earned_traffic` and `document_hidden`.

---

### 8 January 2019 — Support for exports based on tags

You can now create exports based on tags, in addition to searches.

---

## Compliance

# Compliance Changes

It is important to us that we provide fully-compliant APIs to our customers. As data providers update their terms over time we need to adjust our APIs to ensure they remain compliant.

On this page we give details of upcoming and past changes to the API for compliance reasons. If you have any questions about the recent changes please contact our [Support team](/help/support).

### 26th April 2022: Removal of YouTube reach field

In order to maintain compliance with the Terms of Service for YouTube we are no longer able to provide reach values for YouTube.

### 18th November 2020: Changes to Twitter and YouTube fields

To stay compliant with the latest Terms of Service for Twitter and YouTube we made some changes to the fields we provide through the Meltwater API.

#### Twitter

Currently the Meltwater API provides Tweet URLs and Author handles for each tweet. We replaced these fields for tweets with the Tweet ID and the Author ID. Essentially the API provides Twitter's numeric identifiers for the tweet and its author, rather than the URL and handle.

| Product / format | Previous fields | New fields |
|------------------|-----------------|------------|
| Meltwater API - CSV | `URL`, `Influencer` | `Tweet Id`, `Twitter Id` |
| Meltwater API - JSON | `document_url document_authors[].name` | `document_external_id document_authors[].author_external_id` |

#### YouTube

The Meltwater API previously provided the AVE field for YouTube data. To comply with YouTube terms of service this field was redacted from the API.

---

## FAQs

<Head>
<script type="application/ld+json">{JSON.stringify({
  '@context': 'https://schema.org',
  '@type': 'FAQPage',
  mainEntity: [
    {
      '@type': 'Question',
      name: 'How can I get access to the Meltwater API?',
      acceptedAnswer: { '@type': 'Answer', text: 'If you are a Meltwater customer please speak to your account manager to check if your package has access to the Meltwater API.' },
    },
    {
      '@type': 'Question',
      name: 'Do you have an SDK or Client Libraries?',
      acceptedAnswer: { '@type': 'Answer', text: 'Currently, we do not create our own, though we do provide an Open API specification which allows you to generate your own.' },
    },
    {
      '@type': 'Question',
      name: 'How much data can I export using the API?',
      acceptedAnswer: { '@type': 'Answer', text: 'Your export limits depend on your Meltwater package. Customers with inclusive API access can export up to 30,000 documents per month. Customers with an API package have their limit stated in their contract. See the Usage Limits page for full details.' },
    },
    {
      '@type': 'Question',
      name: 'How many exports can I run at one time?',
      acceptedAnswer: { '@type': 'Answer', text: 'You can create as many exports as you want. However only one export will be processed at a time. If you have scheduled multiple exports at the same time, all outstanding exports will remain in a PENDING state until the first export completes.' },
    },
    {
      '@type': 'Question',
      name: 'How many searches can I use for an export?',
      acceptedAnswer: { '@type': 'Answer', text: 'For an export request you can specify up to 5 searches or tags.' },
    },
    {
      '@type': 'Question',
      name: 'How long does it take to generate my export?',
      acceptedAnswer: { '@type': 'Answer', text: 'Generating an export takes anywhere from a few minutes to 30 minutes. The more data involved and the bigger the time period, the longer it will take for an export to complete.' },
    },
    {
      '@type': 'Question',
      name: 'When will the data for my recurring exports be refreshed?',
      acceptedAnswer: { '@type': 'Answer', text: 'Your export will be refreshed 30 minutes after the end of the time period that you have selected for your export. For example if you run a daily export starting at 00:00, then your export will begin to refresh at 00:30.' },
    },
    {
      '@type': 'Question',
      name: 'Does the export window include the Start Date and End Date?',
      acceptedAnswer: { '@type': 'Answer', text: 'The export time window begins at, and includes the Start Date, and continues up to, but not including the End Date. For example, to include all documents published on December 25th 2018, use a Start Date of 2018-12-25T00:00:00 and End Date of 2018-12-26T00:00:00.' },
    },
    {
      '@type': 'Question',
      name: 'Do you delete exported data?',
      acceptedAnswer: { '@type': 'Answer', text: 'For one-time exports, we automatically delete exported data 30 days after the export is executed. For recurring exports, if you do not access the data for over 30 days your recurring export will be cancelled.' },
    },
    {
      '@type': 'Question',
      name: 'From which IPs will Meltwater push documents to my data streams?',
      acceptedAnswer: { '@type': 'Answer', text: 'You can whitelist the following IPs: 34.247.101.20/32, 34.247.65.50/32, and 34.248.44.159/32.' },
    },
    {
      '@type': 'Question',
      name: 'Why do I receive older documents that are not from today?',
      acceptedAnswer: { '@type': 'Answer', text: 'Through the Streaming API you may receive documents with a document_publish_date that is older than the current day. You should expect to receive documents that are up to 31 days old. This can happen due to delayed ingestion, updated articles, or changes to our source list.' },
    },
    {
      '@type': 'Question',
      name: 'How many documents can I import in a single BYOC request?',
      acceptedAnswer: { '@type': 'Answer', text: 'Currently, you can import up to 500 documents in a single request. If you need to import more documents, you can send multiple requests.' },
    },
    {
      '@type': 'Question',
      name: 'How quickly will I see my imported documents in the Meltwater platform?',
      acceptedAnswer: { '@type': 'Answer', text: 'Imported documents are typically processed and indexed within a few minutes. However, the exact time may vary based on the volume of documents being imported and the current load on the system.' },
    },
    {
      '@type': 'Question',
      name: 'How many requests can I make to the BYOC endpoints?',
      acceptedAnswer: { '@type': 'Answer', text: 'The BYOC endpoints are subject to the same rate limits as other Meltwater API endpoints — 100 calls per minute. This translates to approximately 50,000 documents per minute if you are importing the maximum of 500 documents per request.' },
    },
  ],
})}</script>
</Head>

# Frequently Asked Questions

## General

**How can I get access to the Meltwater API?**

If you are a Meltwater customer please speak to your account manager to check if your package has access to the Meltwater API.

**Do you have an SDK or Client Libraries?**

Currently, we do not create our own, though we do provide an [Open API specification](/api-reference/api-reference-overview) which allows you to generate your own.

---

## Listening Exports

**How much data can I export using the API?**

Please take a look at the [Usage Limits](/guides/getting-started/usage-limits) page.

**How many exports can I run at one time?**

You can create as many exports as you want. However only one export will be processed at a time. If you have scheduled multiple exports at the same time, all outstanding exports will remain in a `PENDING` state until the first export completes. Once the running export is complete, the next `PENDING` export will be processed.

**How many searches can I use for an export?**

For an export request you can specify up to 5 searches or tags.

**How long does it take to generate my export?**

Generating an export takes anywhere from a few minutes to 30 minutes. The more data involved and the bigger the time period, the longer it will take for an export to complete.

Please take this into consideration when configuring scheduled refresh in your BI tool or any other service consuming the exported data.

**When will the data for my recurring exports be refreshed?**

Your export will be refreshed 30 minutes after the end of the time period that you have selected for your export. For example if you run a daily export starting at 00:00, then your export will begin to refresh at 00:30.

This 30 minute buffer makes sure that our system has been able to ingest all data for the time period that you have requested.

**Does the export window include the "Start Date" and "End Date"?**

The export time window begins at, and includes the Start Date, and continues up to, but not including the End Date.

For example: If you want to include all the documents published on December 25th, 2018, you would use a Start Date of `2018-12-25T00:00:00` and End Date of `2018-12-26T00:00:00`.

**What are the different status values for an export?**

* `PENDING` — Export is waiting to be processed, or is currently being processed.
* `ACTIVE` — (recurring exports only) Export has data available and will be refreshed periodically.
* `FINISHED` — (one-time export only) Export is complete and data is available.
* `INCOMPLETE` — (one-time export only) Export is finished, but the data is incomplete; you'll need to re-create the export to get the full set of results.
* `CANCELLED` — Export was cancelled by user or administrator. This can happen if the search associated with the export was deleted, or if access to the API has been removed. Data will no longer be accessible for this export.

**Do you delete exported data? And when?**

For one-time exports, we automatically delete exported data 30 days after the export is executed.

For recurring exports, your exports will be updated on your defined time schedule, always providing the newest exported data. If you do not access the data for a recurring export for over 30 days your recurring export will be cancelled.

**Why aren't all the keywords I expect in the matched keywords list?**

The keywords for `document_matched_keywords` are collected from the highlights for the matched document. The highlights is a fragment of the document with a certain length. If the document matches a lot of keywords they might exceed the fragment length, and thus won't be included in the list.

---

## Data Streams

**How can I verify that the incoming document is coming from Meltwater?**

Please see the [Document Verification guide](/guides/listening/datastreams-document-verification).

**From which IPs will Meltwater push documents to my data streams? (IP Whitelisting)**

In addition to the document verification that we offer, you can also whitelist the following IPs as an extra level of security, confirming that the messages being pushed to your destination (`target_url`) are coming from Meltwater:

* `34.247.101.20/32`
* `34.247.65.50/32`
* `34.248.44.159/32`

**While creating a data stream I am getting an error that my `target_url` is invalid. What is the expected format?**

You cannot create the data stream if your `target_url`:

* is a malformed url (missing schema, missing host, etc.)
* contains a host which is a private IP address
* contains a host which is a loopback address or localhost

**I created a data stream but it looks like it disappeared. What happened?**

There are two situations in which this can happen:

* If you create a data stream with a `target_url` that is not valid, we will delete the data stream.

* Similarly, if your `target_url` becomes unavailable and unable to receive content, we will eventually delete the data stream. We will retry 5 times to push data to your `target_url`, with a 5 minute delay between each retry. If your `target_url` does not respond with 2xx within a 30 second timeout on any of those requests, we will delete the hook. Effectively this means that if your service behind the `target_url` is unavailable for a total of 25 minutes, we will delete the hook.

We have implemented this logic to prevent backpressure on our system from queueing up documents for high volume searches.

What this means for you as the API consumer is that you need to choose either of these implementation paths:

**Solution A:** Build your system such that you can do no-downtime releases to the service backing your `target_url`. That way your `target_url` is always up, and your hooks will never get deleted.

**Solution B:** Regularly check that the data stream for the search that you want to stream data for is still active. If not, re-create the hook.

**Why do I receive older documents that are not from today?**

Through the Streaming API you may receive documents with a `document_publish_date` that is "older" than the current day. You should expect to receive documents that are up to 31 days old.

There are various reasons why documents can be republished through our Streaming API:

* The ingestion of data in our system may be delayed. We cannot guarantee that we fetch the original news articles as soon as they have been published by their original source.
* Articles can get updated. You might receive a document with a given `document_publish_date` and then receive an updated document from the same article with an older `document_publish_date`.
* Major changes to our list of news and social sources can also re-trigger documents publishing.

Our general recommendation is:

* Expect every document to contain valuable updates; store (or reprocess) the document in your client.
* If you are storing the document we recommend overwriting an existing document with the same `document_id`. Potentially, the more recently received document will contain updated and relevant information.

**What is the maximum amount of data streams I can create?**

Please take a look at the [Usage Limits](/guides/getting-started/usage-limits) page.

**Will I be notified if a data stream is deleted due to an unavailable `target_url`?**

Yes, if a data stream is deleted because the `target_url` becomes unavailable, we will notify you through two channels:

* **Email Notification:** We will send an email to the registered account email address, detailing the issue and the specific data stream that has been affected.
* **In-App Notification System:** Additionally, a notification will be sent to your account on our application.

---

## Bring Your Own Content

**Where can I find the BYOC API endpoints specification?**

All Meltwater APIs, including BYOC endpoints can be found in the [API Endpoints Reference](/api-reference/api-reference-overview).

**How many documents can I import in a single request?**

Currently, you can import up to 500 documents in a single request. If you need to import more documents, you can send multiple requests.

**What if the current document schema does not support the content type I want to import?**

If your content cannot be represented using the existing fields (`originPlatform` and `contentType`), contact Meltwater Support. We may be able to extend the schema to support additional content types or platforms.

**What happens if one or multiple documents in a batch fail?**

If one or more documents are rejected / invalid due to schema validation, then the whole batch will be rejected with a corresponding error message. You will need to fix the issues and re-submit the whole batch.

**How easily can I identify underlying issues with rejected documents?**

When a batch is rejected, the response will include detailed error messages for each document that failed validation. This will help you identify and fix issues quickly.

**How can I monitor the status of my imported documents?**

You can monitor the status of your imported documents using the `/imports/batches` and `/imports/import_tags` endpoints. These endpoints allow you to retrieve information about all batches, including their status (e.g., `PENDING`, `FINISHED`, `FAILED`) and statistics on the number of documents sent and indexed. For more details, please refer to the [Monitoring Import Progress And Status](/guides/bring-your-own-content/monitoring-imported-data) guide.

**How can I automate my imports?**

You can automate your imports by scheduling regular API requests to the `/imports/documents` endpoint. You can use tools like cron jobs, task schedulers, or workflow automation platforms to set up recurring imports based on your needs.

**How quickly will I see my imported documents in the Meltwater platform?**

Imported documents are typically processed and indexed within a few minutes. However, the exact time may vary based on the volume of documents being imported and the current load on the system.

**How can I track progress of a set of document batches that can be considered to be a single group?**

You can use the `import_tag` query parameter when submitting your batches. This allows you to assign a common tag to related batches, making it easier to filter and track their progress using the `/imports/batches` and `/imports/import_tags` endpoints.

**How many requests can I make to the BYOC endpoints?**

The BYOC endpoints are subject to the same rate limits as other Meltwater API endpoints. You can find more information about rate limits in the [Usage Limits](/guides/getting-started/usage-limits) guide.

Ultimately, you can make 100 calls per minute, which is shared across all API endpoints you have access to. This translates to approximately 50,000 documents per minute if you are importing the maximum of 500 documents per request.

---

## Migration to V3

# Migrating to API Version 3

This guide explains the changes made to the API resulting in version 3.

## Recent changes

We have been working to consolidate our API products into one consistent API.

The latest release brings together the content export features and analytics features of the Export API and Analytics API into one product called the **Meltwater API**.

## What does this mean for your integration?

If you are a current Export API or Analytics API user you can continue to use the API as before. However, we are planning to deprecate these endpoints so we encourage you to plan your migration.

### New endpoint paths

If you have an existing integration the endpoints you call have an inconsistent set of prefixes, for example:

* `/export/v1`
* `/oauth2`
* `/v2`

For the new API version we have tidied-up all export and analytics endpoints under a top level version number. All endpoints in the V3 API have the form `/v3/<feature>/...`

### Authorisation

For the new API we have removed the need for OAuth when calling the API. For V3 endpoints you simply need to provide your API token as the `apikey` header:

```shell
curl -X GET \
  --url "https://api.meltwater.com/v3/searches" \
  --header "Accept: application/json" \
  --header "apikey: **********"
```

*Note that in previous documentation the API token was called the `User Key`.*

## How to migrate

The endpoint parameters have not changed for the new API version. Therefore migrating to the new version is as simple as:

* Removing OAuth calls from your code
* For each endpoint you call...
    * Use the list of endpoint paths below to find the new path
    * Call the new path with the same parameters
    * Provide the same value you do currently in the `user-key` header as the `apikey` header instead

## New endpoint paths

| Verb | Previous path | Version 3 path |
|------|---------------|----------------|
| **Analytics** | | |
| GET | `/v1/analytics/{searchId}` | `/v3/analytics/{searchId}` |
| GET | `/v1/analytics/{searchId}/top_tags` | `/v3/analytics/{searchId}/top_tags` |
| GET | `/v1/analytics/{searchId}/top_shared` | `/v3/analytics/{searchId}/top_shared` |
| GET | `/v1/analytics/{searchId}/top_sources` | `/v3/analytics/{searchId}/top_sources` |
| **Companies** | | |
| GET | `/export/v1/companies` | `/v3/accounts/me/companies` |
| GET | `/v2/companies` | `/v3/accounts/me/companies` |
| **Recurring Exports** | | |
| DELETE | `/export/v1/exports/recurring/{id}` | `/v3/exports/recurring/{id}` |
| GET | `/export/v1/exports/recurring` | `/v3/exports/recurring` |
| GET | `/export/v1/exports/recurring/{id}` | `/v3/exports/recurring/{id}` |
| POST | `/export/v1/exports/recurring` | `/v3/exports/recurring` |
| **One-Time Exports** | | |
| DELETE | `/export/v1/exports/one-time/{id}` | `/v3/exports/one-time/{id}` |
| GET | `/export/v1/exports/one-time` | `/v3/exports/one-time` |
| GET | `/export/v1/exports/one-time/{id}` | `/v3/exports/one-time/{id}` |
| POST | `/export/v1/exports/one-time` | `/v3/exports/one-time` |
| **Searches** | | |
| DELETE | `/export/v1/searches/{id}` | `/v3/searches/{id}` |
| GET | `/export/v1/searches` | `/v3/searches` |
| GET | `/export/v1/searches/{id}` | `/v3/searches/{id}` |
| GET | `/export/v1/searches/{id}/count` | `/v3/searches/{id}/estimate` |
| POST | `/export/v1/searches` | `/v3/searches` |
| PUT | `/export/v1/searches/{id}` | `/v3/searches/{id}` |
| DELETE | `/v2/searches/{id}` | `/v3/searches/{id}` |
| GET | `/v2/searches` | `/v3/searches` |
| GET | `/v2/searches/{id}` | `/v3/searches/{id}` |
| GET | `/v2/searches/{id}/count` | `/v3/searches/{id}/estimate` |
| POST | `/v2/searches` | `/v3/searches` |
| PUT | `/v2/searches/{id}` | `/v3/searches/{id}` |
| **Source Selections** | | |
| GET | `/export/v1/source_selections` | `/v3/source_selections` |
| **Tags** | | |
| GET | `/export/v1/tags` | `/v3/tags` |
| **Hooks** | | |
| DELETE | `/v2/hooks/{id}` | `/v3/hooks/{id}` |
| GET | `/v2/hooks` | `/v3/hooks/{id}` |
| GET | `/v2/hooks/{id}` | `/v3/hooks/{id}` |
| POST | `/v2/hooks` | `/v3/hooks` |
| **Schemas** | | |
| POST | `/v2/schemas/social_streaming.json` | `/v3/schemas/social_streaming.json` |
| POST | `/v2/schemas/editorial_streaming.json` | `/v3/schemas/editorial_streaming.json` |
| POST | `/v2/schemas/broadcast_streaming.json` | `/v3/schemas/broadcast_streaming.json` |

---

## Support


As an API user we recommend you subscribe to updates from our [Status Page](https://status.api.meltwater.com). This will make sure you are aware of any planned maintenance or incidents that may interrupt your usage.

If you need help from our Support team, please get in touch at [help@meltwater.com](mailto:help@meltwater.com).

Or talk to our support team whilst in the Meltwater application, by clicking the help button in the bottom right on any screen.

---

## Connect to Meltwater API

<BrowserOnly>
  {() => <ConsoleLoginForm />}
</BrowserOnly>

---

## Analyze


Use this tool to explore the analytics features of the Listening API.

<AnalyticsConsole />

---

## Export


Use this tool to manage your one-time and recurring exports on the Listening API.

<ExportConsole />

---

## Search


Use this tool to better understand the search feature of the Listening API.

<SearchConsole />

---

## Stream


Use this tool to manage your Listening API real-time streams.

<StreamingConsole />

---

## Projects(Mira-api-console)


Use this tool to list Mira API Projects available to your account. Projects allow you to ground Mira API responses with top-level instructions and Meltwater assets.

<MiraProjectsConsole />

---

## Responses(Mira-api-console)


Use this tool to better understand how to send prompts and continue conversations with Mira using the Mira API.

<MiraResponsesConsole />

---

## Tools Overview


Use the tools to understand more about the Meltwater API.

## Listening Tools

Learn more about the Listening API by carrying out exports, searches, and analysis on mentions data.

| Tool | What it does |
|------|-------------|
| [Export](./listening-console/export) | Create one-time and recurring exports of mentions from your saved searches and tags |
| [Search](./listening-console/search) | Run live searches against your saved searches and inspect individual documents |
| [Analyze](./listening-console/analytics) | Query the analytics API to aggregate volume, sentiment, and reach over time |
| [Stream](./listening-console/streaming) | Create and manage real-time data streams that push documents to a webhook URL |

## Mira API Tools

Learn more about the Mira API, Meltwater's AI platform, by running example prompts.

| Tool | What it does |
|------|-------------|
| [Responses](./mira-api-console/mira-responses) | Send prompts to Mira and explore the Responses API with streaming and conversation threading |
| [Projects](./mira-api-console/mira-projects) | Create and manage Mira AI projects that provide context and instructions to Mira |