API Reference
The Meltwater API is a RESTful API at https://api.meltwater.com that provides programmatic access to Meltwater content, analytics and insights.
Start with the Getting Started guide 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.
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.
For API calls, authentication is performed by providing the API token as a header named apikey on the request.
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.
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.
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