Exporting Mentions

In this tutorial we'll cover the basics of creating an export from an Explore+ search using the API.

Beta feature

Explore+ exports are currently in Beta. The functionality and request/response formats described on this page may change before general availability. If you'd like to take part in the Beta, please contact your Meltwater representative.

Before you start

To run through this tutorial, you will need:

Your Meltwater API token
An Optimized Search in your Explore+ instance

This guide is the Explore+ equivalent of Exporting Mentions for Listening. The concepts are the same, but exports are based on Explore+ searches and use the v4 API request format.

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 an Explore+ search

Exports are created from one or more existing Explore+ searches.

In this tutorial we'll use an existing search, but you can create / edit searches using the API. See the Managing Saved 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/explore_plus/assets/searches endpoint to list your current searches:

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

Use the id returned for a search when specifying the query.searches of your export request.

Understanding common export options

The following options are available for both one-time and recurring exports.

Timezone

You must specify a timezone for your export using the top-level tz parameter in your request. The timezone must be a valid zone as detailed in the IANA database.

The timezone will be used for:

The output dates & times in export result output
For one-time exports - the start and end time
For recurring exports - the schedule you configure (for example the time of day to run the export)

Searches

All exports are based on Explore+ searches. You can use the common all / any / none syntax to specify which searches to pull mentions from for the export.

all - include mentions present in ALL of these searches.
any - include mentions present in ANY of these searches.
none - filter out any mentions in this searches.

You must specify at least one search in the all or any field.

For example, the following searches block would include mentions in searches 12345 or 12346, but exclude any mentions in search 12347:

"searches": {
  "any": [12345, 12346],
  "none": [12347]
}

Output template

When you request an export you specify an output template to be used using the output.template field. The available templates are documented on the Export & Streaming Output Templates page.

Currently only the "API JSON" template is supported for this feature.

To use the "API JSON" template, set the output block of your request as follows:

"output": {
  "format": "json",
  "template": "api.json"
}

Filtering results

Explore+ exports support filtering the matched documents before they are exported, using the query.filters block. You can combine any of the following filters:

tags - include or exclude documents by tag ID (integer).
filter_sets - include or exclude documents by filter set ID (integer).
author_lists - include or exclude documents by author list ID (integer).
custom_fields - include or exclude documents by the values of a custom field. Keyed by custom field ID, with each value matched using the operators below. See Custom Fields Management for how to list the custom fields and value IDs available in your instance.
languages - include or exclude documents by ISO 639-1 language code (for example en, de).
countries - include or exclude documents by ISO 3166-1 alpha-2 country code (for example us, gb, de).
sources - include or exclude documents by content source (for example facebook, instagram, x, news_online, youtube, tiktok); see the Create export reference for the full list of supported sources.
sentiments - include or exclude documents by sentiment: positive, negative, or neutral.

Each filter accepts one or more match operators:

all - the document must match all of the listed values.
any - the document must match at least one of the listed values.
none - the document must match none of the listed values.

For example, the following filters block keeps only documents tagged with 123465879, excludes any document where custom field 4716 has the value 6766, and excludes English-language documents:

"filters": {
  "tags": {
    "all": [123465879]
  },
  "custom_fields": {
    "4716": {
      "none": [6766]
    }
  },
  "languages": {
    "none": ["en"]
  }
}

The additional filters use the same structure. For example, the following filters block keeps only documents from facebook or x, published in the US or UK, with positive sentiment, drawn from filter set 9001 and author list 7777:

"filters": {
  "sources": {
    "any": ["facebook", "x"]
  },
  "countries": {
    "any": ["us", "gb"]
  },
  "sentiments": {
    "all": ["positive"]
  },
  "filter_sets": {
    "all": [9001]
  },
  "author_lists": {
    "all": [7777]
  }
}

Creating a one-time export

One-time exports are created by setting type to "onetime". You need to provide a provider, a top-level tz, a period, a query (with at least one search), and an output.

Note that the timezone applies to the start and end of the period, and is provided via the top-level tz field (not inside period).

curl --location 'https://api.meltwater.com/v4/content/export' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apikey: **********' \
--data '{
  "provider": "explore_plus",
  "type": "onetime",
  "tz": "UTC",
  "period": {
    "start": "2026-01-01T00:00:00",
    "end": "2026-04-07T00:00:00"
  },
  "query": {
    "searches": {
      "all": [51002887]
    },
    "filters": {
      "tags": {
        "all": [123465879]
      },
      "custom_fields": {
        "4716": {
          "none": [6766]
        }
      },
      "languages": {
        "none": ["en"]
      }
    }
  },
  "output": {
    "format": "json",
    "template": "api.json"
  }
}'

A successful request returns 201 Created. The export job is echoed back with a server-assigned config block (including the job id, status, and the download url), and the submitted query resolved to the matching search names.

Example response:

{
  "provider": "explore_plus",
  "type": "onetime",
  "tz": "UTC",
  "period": {
    "start": "2026-01-01T00:00:00",
    "end": "2026-04-07T00:00:00"
  },
  "config": {
    "id": 1,
    "url": "https://exports.meltwater.io/v4/explore-plus-one-time/1?data_key=bd011779-bf14-381b-9f03-459bf0ce2d7b",
    "created_at": "2026-04-01T00:00:00Z",
    "updated_at": "2026-04-01T00:00:00Z",
    "status": "PENDING",
    "status_reason": ""
  },
  "query": {
    "searches": {
      "all": [
        { "id": 51002887, "name": "Brand mentions" }
      ]
    }
  },
  "output": {
    "format": "json",
    "template": "api.json"
  }
}

Fetching one-time export results

You can check the status of a one-time export using the GET /v4/content/export/<export_id> endpoint.

curl -X GET \
  --url "https://api.meltwater.com/v4/content/export/<export_id>" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The export status is returned in config.status. Once it is FINISHED, the export output is available for download at config.url. While the export is still being generated the status will be PENDING.

Export execution time

The size of an export depends on how many results the search generates, and how large a 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

The result you download from the config.url is an object containing a documents array and the export_id:

{
  "documents": [
    "<an object for each document in the export, as described on the Output Templates page>"
  ],
  "export_id": 17985466
}

The shape of each object in the documents array is determined by the output template you chose. See the Export & Streaming Output Templates page for the full field-by-field breakdown.

Creating a recurring export

Recurring exports run on a schedule you specify. Each time the schedule runs it overwrites the data at config.url with a fresh export.

Specifying a time window and schedule

To create a recurring export, set type to "recurring". The request is the same as a one-time export, with one difference: instead of giving period a fixed start and end, you describe a schedule and a rolling data window:

period.cron - a standard five-field cron expression (minute hour day-of-month month day-of-week) that controls when each export run is triggered. The top-level tz is used to interpret the schedule.
period.window_size and period.window_unit - control how much data each run covers, as a rolling window ending at the run time. For example window_size: 1 with window_unit: "day" includes the previous day of data in each run.

For example, the following period runs the export every day at 06:00 (in the export's timezone), with each run covering the previous day of data:

"period": {
  "cron": "0 6 * * *",
  "window_size": 1,
  "window_unit": "day"
}

Creating a recurring export via API

Recurring exports are created using the same POST /v4/content/export endpoint as one-time exports.

curl --location 'https://api.meltwater.com/v4/content/export' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'apikey: **********' \
--data '{
  "provider": "explore_plus",
  "type": "recurring",
  "tz": "UTC",
  "period": {
    "cron": "0 6 * * *",
    "window_size": 1,
    "window_unit": "day"
  },
  "query": {
    "searches": {
      "all": [51002887]
    }
  },
  "output": {
    "format": "json",
    "template": "api.json"
  }
}'

A successful request returns 201 Created. As with one-time exports, the job is echoed back with a server-assigned config block. For recurring exports this also includes config.next_run_date, and the status will be ACTIVE once the export is scheduled.

Example response:

{
  "provider": "explore_plus",
  "type": "recurring",
  "tz": "UTC",
  "period": {
    "cron": "0 6 * * *",
    "window_size": 1,
    "window_unit": "day"
  },
  "config": {
    "id": 2,
    "url": "https://...",
    "created_at": "2026-04-01T00:00:00Z",
    "updated_at": "2026-04-01T00:00:00Z",
    "next_run_date": "2026-08-15T06:00:00Z",
    "status": "ACTIVE",
    "status_reason": ""
  },
  "query": {
    "searches": {
      "all": [
        { "id": 51002887, "name": "Brand mentions" }
      ]
    }
  },
  "output": {
    "format": "json",
    "template": "api.json"
  }
}

Fetching recurring export results

You can check the status of a recurring export using the same GET /v4/content/export/<export_id> endpoint as one-time exports.

curl -X GET \
  --url "https://api.meltwater.com/v4/content/export/<export_id>" \
  --header "Accept: application/json" \
  --header "apikey: **********"

For a recurring export, the response additionally includes:

config.next_run_date - when the export is next scheduled to run.
history - a list of previous runs, each with its own status and the period of data it covered.

{
  "config": {
    "id": 2,
    "next_run_date": "2026-08-15T06:00:00Z",
    "status": "ACTIVE",
    "url": "https://..."
  },
  "history": [
    {
      "status": "FINISHED",
      "period": {
        "start": "2026-04-01T00:00:00",
        "end": "2026-04-30T23:59:59"
      },
      "created_at": "2026-05-01T00:00:00Z",
      "updated_at": "2026-05-01T00:05:00Z"
    }
  ]
}

The latest run's output is always available at config.url. Each scheduled run overwrites the data at that URL with fresh results.

Listing your exports

You can list all of your exports using the GET /v4/content/export endpoint. This returns both one-time and recurring exports.

The provider query parameter is required - set it to explore_plus to list your Explore+ exports.

curl -X GET \
  --url "https://api.meltwater.com/v4/content/export?provider=explore_plus" \
  --header "Accept: application/json" \
  --header "apikey: **********"

The endpoint supports the following optional query parameters:

schedule_type - filter by export type, either onetime or recurring. By default both types are returned.
page - the page of results to fetch. Defaults to 1.
page_size - the number of exports to fetch per page. Defaults to 10, max is 100.

Results are returned in a paginated data array, alongside the total count and the current page and page_size:

{
  "count": 2,
  "page": 1,
  "page_size": 10,
  "data": [
    {
      "provider": "explore_plus",
      "type": "onetime",
      "tz": "UTC",
      "period": {
        "start": "2026-04-01T00:00:00",
        "end": "2026-04-30T23:59:59"
      },
      "config": {
        "id": 99,
        "url": "https:...",
        "status": "FINISHED",
        "status_reason": ""
      },
      "query": {
        "searches": {
          "all": [
            { "id": 12345, "name": "Brand mentions" }
          ]
        }
      },
      "output": {
        "format": "json",
        "template": "api.json"
      }
    },
    {
      "provider": "explore_plus",
      "type": "recurring",
      "tz": "UTC",
      "period": {
        "cron": "0 6 * * *"
      },
      "config": {
        "id": 100,
        "url": "https://...",
        "next_run_date": "2026-08-15T06:00:00Z",
        "status": "ACTIVE",
        "status_reason": ""
      },
      "query": {
        "searches": {
          "all": [
            { "id": 12345, "name": "Brand mentions" }
          ]
        }
      },
      "output": {
        "format": "json",
        "template": "api.json"
      }
    }
  ]
}

Deleting an export

You can delete an export - one-time or recurring - using the DELETE /v4/content/export/<export_id> endpoint. Deleting a recurring export cancels its schedule so that no further runs take place.

curl -X DELETE \
  --url "https://api.meltwater.com/v4/content/export/<export_id>" \
  --header "Accept: application/json" \
  --header "apikey: **********"

A successful request returns 204 No Content. If no export exists with the given id, the endpoint returns a 404 Not Found.

Before you start​

Types of export​

Obtaining an Explore+ search​

Understanding common export options​

Timezone​

Searches​

Output template​

Filtering results​

Creating a one-time export​

Fetching one-time export results​

Understanding export results​

Creating a recurring export​

Specifying a time window and schedule​

Creating a recurring export via API​

Fetching recurring export results​

Listing your exports​

Deleting an export​