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"
      ]
    }
  ]
}
Example: "Likes" in October, compared to September.

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:likes
  • Impressions

    Number of users viewing a campaign. We only count impressions on promoted content. Therefore, organically generated impressions are not counted.

    tads:impressions
  • Total 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:engagements
  • Retweets

    Total number of retweets your ads received.

    tads:retweets
  • Unfollows

    Number of people who stopped following your account from an ad.

    tads:unfollows
  • Clicks

    Total clicks on links, hashtags, a Website Card, and other Tweet details in your ad, combined with likes and profile clicks.

    tads:clicks
  • Replies

    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:replies
  • Total 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_clicks
  • App clicks

    Number of app button clicks (clicks to install or open an app).

    tads:app_clicks
  • CPE

    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:cpe
  • CPC

    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:cpc
  • Spend

    The total estimated amount you spent on your campaign.

    tads:spend
  • Engagement 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.