Searching Mentions

In this tutorial we’ll get you up and running to make your first search calls.

Note that you can try analytics calls using the Search Console tool before you write any code.

Before you start

To run through this tutorial, you will need:

• Your Meltwater API token
• A Saved Search in your Meltwater App account

Authentication

You need to provide your API token when you call any Meltwater API endpoint.

You provide the API token as a header called apikey, for example:

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

For full details take a look at the Authentication page.

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

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

Example response:

{
  "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:

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 page 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 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.

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.

{
    "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:

{
    "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 an array of documents (mentions) using the output template you requested.