Metrics
X Ads metrics via API
Your customer connects their X Ads account and your product queries 14 metrics through the same endpoint as every other platform. Each metric has an id (reference_key) that goes in the request.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"comparison_start": "2026-09-01",
"comparison_end": "2026-09-30",
"metrics": [
{
"id": "m1",
"reference_key": "tads:likes",
"component": "number_v1",
"metrics": [
"likes"
],
"dimensions": [
"engagement"
]
}
]
}More X Ads request examples
The same endpoint for every kind of metric. The metrics and dimensions of each item come from the platform catalog (GET /api/metrics/{integration_slug}).
Table
Featured campaigns
Campaigns that had the greatest impact on your audience during the period analyzed.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "tads:featured_campaigns",
"component": "datatable_v1",
"metrics": [
"likes",
"replies",
"retweets",
"billed_charge_local_micro",
"total_clicks",
"engagements"
],
"dimensions": [
"engagement"
]
}
]
}Number
Impressions
Number of users viewing a campaign. We only count impressions on promoted content. Therefore, organically generated impressions are not counted.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "tads:impressions",
"component": "number_v1",
"metrics": [
"impressions"
],
"dimensions": [
"engagement"
]
}
]
}Numbers
13 metrics
Likes
Total number of likes your ads received.
tads:likesImpressions
Number of users viewing a campaign. We only count impressions on promoted content. Therefore, organically generated impressions are not counted.
tads:impressionsTotal Engagement
Engagement indicates the number of user interactions with your campaign. Engagements count all Tweet clicks, including Retweets, replies, likes, poll votes and clicks on hashtags.
tads:engagementsRetweets
Total number of retweets your ads received.
tads:retweetsUnfollows
Number of people who stopped following your account from an ad.
tads:unfollowsClicks
Total clicks on links, hashtags, a Website Card, and other Tweet details in your ad, combined with likes and profile clicks.
tads:clicksReplies
Total number of responses your ads received. Replies are a Tweet in response to another Tweet. It's usually published when you click the Reply button next to the Tweet in your timeline. A response always starts with @username.
tads:repliesTotal Clicks
Total number of clicks on your ads. Includes URL clicks (shortened or normal links), profile picture, screen name, username, details, hashtags, likes, and app clicks (clicks to install or open an app).
tads:total_clicksApp clicks
Number of app button clicks (clicks to install or open an app).
tads:app_clicksCPE
Cost per engagement (CPE) represents on average how much each engagement cost you. It is calculated by dividing the total campaign spend by the number of engagements (such as Likes, Retweets and Replies).
tads:cpeCPC
Cost Per Click (CPC) represents on average how much each click costs you. It is calculated by dividing the total campaign spend by the total number of clicks.
tads:cpcSpend
The total estimated amount you spent on your campaign.
tads:spendEngagement rate
The Engagement rate represents the total interactions on your ad, taking into account their impressions. It is calculated by dividing the total number of interactions (likes, retweets, responses, clicks and followers gained) by the volume of impressions.
tads:engagement_rate
Tables
1 metric
Featured campaigns
Campaigns that had the greatest impact on your audience during the period analyzed.
tads:featured_campaigns
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
