Fetching Campaigns & Metrics
In this tutorial we'll cover how to fetch your influencer campaigns and their related posts, influencers and metrics using the API.
For an introduction to the concepts referenced here, see the Influencer Campaigns overview.
Before you start
To run through this tutorial you will need:
- Your Meltwater API token
- Access to Klear influencer campaigns on your Meltwater account
- At least one campaign set up in Klear
The same API token is used across all Meltwater API features. If you already have a token for another feature you can use the same one - see API Credentials to create or manage your token.
All the endpoints in this guide are GET requests, take no request body, and are limited to 100 calls per minute.
The typical flow
Most integrations follow the same sequence:
- Optionally list your workspaces to find the group of campaigns you care about.
- Optionally list your influencer tags to find the tags you want to filter by.
- List your campaigns to get their IDs.
- For each campaign ID, fetch campaign metrics, posts and influencers.
Fetching workspaces
Klear workspaces let you organise campaigns into groups. Your API token gives you access to every campaign regardless of workspace, but you can use a workspace ID to narrow the campaigns and tags you fetch.
List the workspaces on your account by calling the GET /v3/accounts/me/klear/workspaces endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/accounts/me/klear/workspaces" \
--header "Accept: application/json" \
--header "apikey: **********"
The response contains the workspaces you have access to:
{
"klear_workspaces": [
{
"id": 12345,
"name": "My Workspace",
"created_at": "2024-12-09T15:35:08Z"
}
]
}
The endpoint supports one optional parameter:
company_id- query a company other than your default one. See Multiple Companies.
Keep the id of any workspace you want to filter by - you'll pass it as the klear_workspace_id parameter when listing tags and campaigns.
Fetching influencer tags
Influencer tags group influencers into arbitrary sets, and can be used to filter campaign metrics, posts and influencers.
List the tags on your account by calling the GET /v3/influencers/tags endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/influencers/tags" \
--header "Accept: application/json" \
--header "apikey: **********"
The endpoint supports one optional parameter:
klear_workspace_id- restrict the results to a single Klear workspace, using an ID from the workspaces endpoint.
The response lists the tags in your account:
{
"count": 5,
"tags": [
{
"id": 13546865,
"name": "Beauty",
"color": "#B1C07F",
"influencer_count": 57,
"created_at": "2021-02-08T17:51:54Z"
},
{
"id": 13546866,
"name": "Potential Affiliate",
"color": "#72996C",
"influencer_count": 13,
"created_at": "2022-06-02T17:15:49Z"
}
]
}
Keep the id of any tag you want to filter by - you'll pass it as the tags parameter on the campaign metrics, posts and influencers endpoints. The tags applied to each influencer are also returned by the campaign influencers endpoint.
Fetching campaigns
List the campaigns in your account by calling the GET /v3/influencers/campaigns endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/influencers/campaigns" \
--header "Accept: application/json" \
--header "apikey: **********"
The endpoint supports the following optional parameters:
klear_workspace_id- restrict the results to a single Klear workspace, using an ID from the workspaces endpoint.exclude_inactive- set totrueto return only campaigns with astatusofACTIVE.company_id- query a company other than your default one. See Multiple Companies.
The response contains every campaign in your account, or in the workspace you specified:
{
"count": 10,
"campaigns": [
{
"id": 1234,
"name": "My campaign",
"created_at": "2024-01-11T06:17:30Z",
"num_influencers": 4,
"start": null,
"end": null,
"tracked_keywords": [
"My new brand",
"#mynewbrand",
"@mynewbrand"
],
"labels": [
{
"id": 123,
"label": "emea"
}
],
"status": "ACTIVE"
},
{
"id": 1235,
"name": "My past campaign",
"created_at": "2024-01-26T06:56:07Z",
"num_influencers": 11,
"start": "2024-10-01T17:00:00Z",
"end": "2024-10-31T17:00:00Z",
"tracked_keywords": [
"My brand",
"#mybrand",
"@mybrand"
],
"status": "ARCHIVE"
}
]
}
A few things to note:
- The
idfield is the campaign ID you'll pass to every other endpoint in this guide. startandendarenullfor campaigns that run continuously.statusisACTIVEfor a running campaign andARCHIVEfor one that has been archived in Klear.tracked_keywordsare the terms Klear matches influencer posts against to attribute them to the campaign.labelsare the labels applied to the campaign in Klear, each with anidand alabel. They are returned for information only - there is no label filter on these endpoints.
Fetching campaign metrics
Fetch the high-level metrics for a single campaign by calling the GET /v3/influencers/campaigns/{campaign_id} endpoint, where {campaign_id} is an id from the campaigns list:
curl -X GET \
--url "https://api.meltwater.com/v3/influencers/campaigns/1234" \
--header "Accept: application/json" \
--header "apikey: **********"
The endpoint supports the following optional parameters:
tags- a comma-separated list of influencer tag IDs to restrict the metrics to, for exampletags=13546865.company_id- query a company other than your default one. See Multiple Companies.
The response gives you a metrics object for the campaign as a whole, and a sources object breaking the same campaign down by social network:
{
"id": 1234,
"labels": [
{
"id": 123,
"label": "emea"
}
],
"metrics": {
"num_posts": 166,
"num_influencers": 50,
"total_engagement": 1696826,
"engagement_rate": 2.996,
"total_reach": 21722085,
"total_emv": 3786571.868
},
"sources": {
"facebook": {
"num_posts": 10,
"num_influencers": 3,
"engagement": 6267,
"engagement_rate": 0.168,
"reach": 318615,
"emv": 28660.149,
"stats": {
"comments": 231,
"likes": 6036
}
},
"instagram": {
"num_posts": 115,
"num_influencers": 50,
"engagement": 498766,
"engagement_rate": 1.626,
"reach": 6618822,
"emv": 1316096.034,
"stats": {
"comments": 16227,
"impressions": 465513,
"likes": 480149,
"reach": 59789,
"saved": 2390,
"views": 578521
}
},
"instagram_stories": {
"num_posts": 19,
"num_influencers": 3,
"engagement": 2192,
"engagement_rate": 0.073,
"reach": 68867,
"emv": 65203.276,
"stats": {
"exits": 5724,
"impressions": 69348,
"reach": 68867,
"replies": 15,
"taps_back": 2177,
"taps_forward": 46858
}
},
"tiktok": {
"num_posts": 14,
"num_influencers": 7,
"engagement": 1189522,
"engagement_rate": 7.047,
"reach": 14636441,
"emv": 2369693.359,
"stats": {
"comments": 15841,
"likes": 1169979,
"shares": 3702,
"views": 14636441
}
}
}
}
Only the networks the campaign actually has posts on appear under sources, and the contents of each stats object depend on the network. See the Influencer Campaign Metrics page for the full list of metrics and per-network coverage.
The campaign-level total_reach is not simply the sum of the per-network reach figures, and per-network stats.reach is a different measure again from the network's top-level reach. Report each at the level you fetched it rather than deriving one from the other.
Fetching campaign posts
Fetch the individual posts attributed to a campaign by calling the GET /v3/influencers/campaigns/{campaign_id}/posts endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/influencers/campaigns/1234/posts" \
--header "Accept: application/json" \
--header "apikey: **********"
The endpoint supports the following optional parameters:
sources- a comma-separated list of social networks to restrict the results to, for examplesources=instagram.tags- a comma-separated list of influencer tag IDs to restrict the results to, for exampletags=13546865.company_id- query a company other than your default one. See Multiple Companies.
The response contains the posts for the campaign, or only those from the sources you requested:
{
"id": 1234,
"count": 21,
"posts": [
{
"post_id": "3336290420180556790",
"shortcode": "CXPzqBfvo1o",
"influencer_id": 2314351,
"influencer_name": "Influencer 1",
"source": "instagram",
"post_type": "image",
"body": "Check out this new feature from #mybrand.",
"engagement": 2395,
"reach": 0,
"emv": 5137.605,
"created_at": "2021-12-09T03:27:31Z",
"link": "https://www.instagram.com/p/CXPzqBfvo1o/",
"stats": {
"comments": 53,
"likes": 2342
}
}
]
}
The fields returned for each post depend on the network it was published to. stats in particular varies by network - a TikTok post carries shares and views, an Instagram Story carries taps_forward and exits. See the Influencer Campaign Metrics page for what to expect from each network.
Use influencer_id to join a post back to the influencer record returned by the influencers endpoint below.
Fetching campaign influencers
Fetch the influencers on a campaign, with their performance, by calling the GET /v3/influencers/campaigns/{campaign_id}/influencers endpoint:
curl -X GET \
--url "https://api.meltwater.com/v3/influencers/campaigns/1234/influencers" \
--header "Accept: application/json" \
--header "apikey: **********"
The endpoint supports the following optional parameters:
sources- a comma-separated list of social networks to restrict the results to, for examplesources=instagram.tags- a comma-separated list of influencer tag IDs to restrict the results to, for exampletags=13546865.company_id- query a company other than your default one. See Multiple Companies.
The response contains every influencer associated with the campaign:
{
"id": 1234,
"count": 4,
"influencers": [
{
"id": 2314351,
"name": "Influencer 1",
"email": "influencer1@meltwater.com",
"country": "United States",
"budget": 324.54,
"campaign_metrics": {
"num_posts": 96,
"engagement": 266445,
"engagement_rate": 2.061,
"reach": 1181133,
"emv": 1105666.702,
"sales": {
"USD": 4280
}
},
"influencer_metrics": {
"influence": 81,
"brand_score": 69,
"true_reach": 910343.689,
"followers": 297769,
"sources": {
"facebook": {
"id": 341721626371555,
"username": "influencer 1",
"followers": 2124,
"engagement_per_post": 16.459,
"true_reach": 97.9197
},
"instagram": {
"id": 8686377,
"username": "influencer_1",
"followers": 138645,
"engagement_per_post": 2856.304,
"true_reach": 6692.595036036531
},
"instagram_stories": {
"id": 8686377,
"username": "influencer_1",
"followers": 138645,
"engagement_per_post": 3906.21,
"true_reach": 2051.07
},
"tiktok": {
"id": 6763262540677907461,
"username": "influencer_1",
"followers": 157000,
"engagement_per_post": 4410.649,
"true_reach": 196352
}
}
}
}
]
}
The two metric blocks answer different questions, and it is worth keeping them apart in any report you build:
campaign_metrics- how this influencer performed on this campaign. These figures respect thesourcesandtagsfilters you applied.influencer_metrics- Klear's assessment of the influencer overall, independent of any campaign. Use these for audience size and quality, not campaign performance.
sales is returned as an object keyed by ISO currency code, and is only present where sales attribution is available for the influencer.
Both blocks are documented in full on the Influencer Campaign Metrics page.
Putting it together
A nightly extract for a single campaign would typically:
- Call
GET /v3/influencers/campaignsonce to refresh the campaign list and pick up any new campaigns. - Call
GET /v3/influencers/campaigns/{campaign_id}for the headline numbers. - Call
GET /v3/influencers/campaigns/{campaign_id}/postsand.../influencersfor the detail, joining posts to influencers oninfluencer_id.
Schedule it after 21:00 UTC so it picks up that day's metrics refresh, and keep it within the 100 calls per minute limit if you are iterating over many campaigns.