Query Tweets Metrics via Ads API



How do I query the tweets metrics data from Ads API. Which endpoint would I need to use for it?

Tweets Metrics report is available for manual export from the “https://ads.twitter.com/accounts/” website. I want to query the same data using Ads API.


p.s. the fields inside the Tweets Metrics export are,
status id tweet text tweet start date time spend impressions engagements billed engagements retweets replies follows clicks media engagements likes card engagements unfollows engagement rate call to action eCPE CPE cost per link click currency


Have you tried to read this? https://dev.twitter.com/ads/overview


I have. I am not sure whether it’s LINE_ITEM, PROMOTED_TWEET, or ORGANIC_TWEET or something else that I need to look at to get the similar output as Tweets Metrics export. Thanks


Tweet’s metrics are of the entity type PROMOTED_TWEET.

A PROMOTED_TWEET is nothing but a Tweet that has been promoted in a LINE_ITEM.

Retrieving statistics for tweets


So following this to get the list of promoted tweets, and then, this to get the stats,I should pass in “PROMOTED_TWEET” for “entity”, what should I pass as the “entity_ids” for the stats? Is it the “tweet_ID” of the this export?



Is just the ID field.


Ok, when I pass in an ID as the “entity_id” of “PROMOTED_TWEET” entity in the analytics stats url/parameter, I’m not getting the same output at the Tweets Metrics export from the Twitter UI. For example, there is no status id, tweet text, and etc are not in the data output. Using Billing and Engagement as metric group.


That’s because that endpoint is only to retrieve statistics.

If you want to get that information, you should mix it with a Twitter REST API request in order to retrieve information with the “tweet_id” field.


Are you referring to this? I’m assuming I would need to sort the output of this and pass in the “tweet_id” for “since_id” and “max_id”? Or is there a different endpoint you’re referring to?
Assuming you ARE referring to search tweets, for the GET PROMOTED_TWEETS, does “id” and “tweet_id” have 1 to 1 relationship (for when i want to join tweets with statistics based on id <> tweet_id key fields)?


No, i’m refering to : https://dev.twitter.com/rest/reference/get/statuses/lookup

And the relation between tweets and promoted tweets is not 1 to 1.

Imagine you have 1 Tweet:

Tweet1 -> ID = abc

And you have 2 Line Items and you want to promote that tweet in those 2 line items, so you’ll get:

Promoted_Tweet 1: ID = XXX, tweet_id = abc, line_item_id = qqq
Promoted_Tweet 2: ID = YYY, tweet_id = abc, line_item_id = www

Is the same if you uses the same tweet to promote it in a different campaign.


Ok so here’s what I tried.

I queried the PROMOTED_TWEET endpoint.
Took one of the tweet_id and queried the Statsus/lookup endpoint.
Got the Tweet text.

I then went on to the https://ads.twitter.com/accounts/ and exported the Tweets/Engagement data (with start date 1 day before the “created_date” of the PROMOTED_TWEET’s record).

When I query the “text” or “tweet_id” from the lookup endpoint’s data in the exported file (“tweet_text” or “status_id” respectively), nothing shows up. What am I missing?


Without any data I think I cannot do more…, it looks that your request is ok. But I don’t know whats wrong.

Did you export the correct campaign?


Ok, found one tweet_id and its corresponding stats. One (big) thing though, we didn’t find the “Spend” field (tried using all metric groups). Is the field available somewhere? Thanks


@JvJv If you look at this link: https://dev.twitter.com/ads/analytics/metrics-and-segmentation-in-analytics

You will see that there is a BILLING metric_group. In this metric group, there is a metric called billed_charge_local_micro. This is spend in micro dollars. If you divide this number by 1,000,000, then you will get your spend in dollars.

Hope that helps.


Thanks, that helped! Just one caveat though, the Spend in the export doesn’t match the billed_charge_local_micro/1000000 value. Is that normal? if so, why could that be the case?


It is normal, Twitter’s metrics in their UI tend to be calculated per minute. And per minute stats are not available via the Ads API. You can see that in this link: https://dev.twitter.com/ads/overview/api-vs-ui shown as “Minute granularity for stats”


Ahh, thanks for the info.

Thanks guys for all your help. Will post back if I run into any further issues.



We’re seeing a HUGE difference b/w spend/impressions/etc on the Twitter Analytics page (i.e. https://ads.twitter.com/accounts//campaigns_dashboard…) vs the API data (segmented by Location for example).

for instance, on the webpage (and the report you export from the webpage) has round # for Spend for a specific account/campaign/location/day (refer to Website screenshot). Whereas, in the API data, the same grouped data (billed_charge_local_micro/1000000) rarely sums up to match the value on the webpage and rarely it’s rounded evenly (refer to API/excel screenshot) like we see on the webpage.

Why are the values so different? Where are the spend/impressions/etc values on the website coming from? How does one match these values to API’s queried data?

Update: We pull API data based on Cities, Location, Device, and Gender segmentation type. Which type should we use to get matching data? Location?


Could be that you are viewing in the ads dashboard the data for the whole period, and in the API only for the first hour?

I thing this because of your screenshots



On the dashboard, I’m selecting one day.
In the export (excel), I’m selecting one day (but somehow it only contains data for the last hour of that day. I’m querying the API for the whole period of the Campaign (Campaign Start Date and End Date).

Here’s the API export w/o any segmentation. The total Spend in this excel is still same as before.

The dashboard says $450 for the spend for this campaign whereas API export says $86. Not sure what to do.