Ads API questions

[amit_wds]

We are working on extracting the ads stats data using Twitter Ads API.

1. How can we get the Organic Tweet entity ID. This is one of the required parameter for the stats API call - https://ads-api.twitter.com/2/stats/accounts/:account_id

2. Is there any relationship or hierarchy between the following entities – account, funding_instrument, campaign, line_item, promoted_tweet and organic_tweet? We are trying to understand if we can extract the most granular level stats for the entity and then sum up for the higher-level entities in the hierarchy.

[juanshishido]

Thanks for the questions, @amit_wds.

There are several ways to find the Tweet ID.

The GET accounts/:account_id/scoped_timeline allows you to retrieve Tweet details for organic Tweets (scoped_to=followers) or nullcasted Tweets (scoped_to=none).

$ twurl -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/scoped_timeline?scoped_to=none&trim_user=true&count=1"
{
  "data": [
    {
      "created_at": "Wed Jul 19 20:55:57 +0000 2017",
      "id": 887778056907005952,
      "id_str": "887778056907005952",
      "text": "hello, world https://t.co/5ealGI8kKR",
      "truncated": false,
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": [],
        "media": [
          {
            "id": 887777498917777408,
            "id_str": "887777498917777408",
            "indices": [
              13,
              36
            ],
            "media_url": "http://pbs.twimg.com/amplify_video_thumb/887777498917777408/img/cwavyNV2brPoEOlK.jpg",
            "media_url_https": "https://pbs.twimg.com/amplify_video_thumb/887777498917777408/img/cwavyNV2brPoEOlK.jpg",
            "url": "https://t.co/5ealGI8kKR",
            "display_url": "pic.twitter.com/5ealGI8kKR",
            "expanded_url": "https://twitter.com/apimctestface/status/887778056907005952/video/1",
            "type": "photo",
            "sizes": {
              "thumb": {
                "w": 150,
                "h": 150,
                "resize": "crop"
              },
              "medium": {
                "w": 600,
                "h": 338,
                "resize": "fit"
              },
              "small": {
                "w": 340,
                "h": 191,
                "resize": "fit"
              },
              "large": {
                "w": 1024,
                "h": 576,
                "resize": "fit"
              }
            }
          }
        ]
      },
      "source": "<a href=\"https://ads-api.twitter.com\" rel=\"nofollow\">Ads API Internal Test App</a>",
      "in_reply_to_status_id": null,
      "in_reply_to_status_id_str": null,
      "in_reply_to_user_id": null,
      "in_reply_to_user_id_str": null,
      "in_reply_to_screen_name": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "geo": null,
      "coordinates": null,
      "place": null,
      "contributors": [
        2417045708
      ],
      "retweet_count": 0,
      "favorite_count": 0,
      "favorited": false,
      "retweeted": false,
      "possibly_sensitive": false,
      "scopes": {
        "followers": false
      },
      "lang": "en"
    }
  ],
  "next_cursor": "AAAAAFhLRpQLNF-sGBSgAA",
  "request": {
    "params": {
      "trim_user": true,
      "count": 1,
      "scoped_to": "none",
      "account_id": "18ce54d4x5t"
    }
  }
}

The Tweet ID can be found in the id or id_str response attribute, though we recommend the latter. Note that either type of Tweet (organic or nullcasted) can be promoted in campaigns.

The GET accounts/:account_id/promoted_tweets endpoint allows you to retrieve references to Tweets associated with line items. These are Tweets promoted in campaigns.

$ twurl -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/promoted_tweets?count=1"
{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8sxrn1xxc",
  "data": [
    {
      "line_item_id": "5tddn",
      "id": "x73d7",
      "entity_status": "ACTIVE",
      "created_at": "2016-07-29T22:25:45Z",
      "updated_at": "2016-12-05T23:33:37Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "759137621666766848",
      "deleted": false
    }
  ]
}

The Tweet ID can be found in the tweet_id response attribute.

promoted_tweets entities are associations between Tweets and line items—this is how we represent Tweets promoted in campaigns. These entities have their own IDs. In this example, Tweet 759137621666766848 is associated with line item 5tddn and the entity’s ID is x73d7.

When using the GET stats/accounts/:account_id endpoint, you’d use the following entity_ids depending on what data you’re interested in retrieving:

• entity_ids=759137621666766848 when entity=ORGANIC_TWEET
• entity_ids=x73d7 when entity=PROMOTED_TWEET

The former retrieves Tweet stats in the organic context, outside of any campaign. The latter retrieves stats in the promoted context, for the Tweet associated with the specific line item.

---

In terms of the hierarchy, please see our Hierarchy and Terminology page. Ads accounts are at the top of the hierarchy. Funding instruments belong to ads accounts. Campaigns are created under funding instruments and line items are created under campaigns. Tweets (think of this as organic Tweet) can be associated with line items—these are the promoted_tweets entities and are the most granular entities.

Do request data (ideally) at the line_items and promoted_tweets level, as you can always aggregate and roll these metrics up to get totals across the entire ads entity hierarchy (i.e. for the campaign, funding instrument or account levels).

• Source

Hope this helps!

[amit_wds]

Thanks @juanshishido for the quick response. I have 2 questions related to your response.

1. Why it is recommended to request metrics data at line_items and promoted_tweets level and why not just at promoted level? Since line_items are composed of promoted tweets. Can we only fetch the metrics data at the promoted tweets level?

2. Is this hierarchy applicable for all the metrics in the metrics groups - account, funding_instrument, campaign, line_item, promoted_tweet and organic_tweet? So we need to fetch all the metrics at the promoted tweets level only?

[juanshishido]

It is possible to request stats for any of the following entities: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, or PROMOTED_TWEET.

Because it’s possible to aggregate to other entities up the hierarchy, the recommendation is to request data at the line item or promoted Tweet. This allows partners to display or use data across the entire ads entity hierarchy, if they so choose, and to avoid making unnecessary requests.

Since line_items are composed of promoted tweets. Can we only fetch the metrics data at the promoted tweets level?

That’s correct. You can choose to only fetch promoted_tweets-level data. (The text in the documentation states, "line_items and promoted_tweets," but that should be "line_items or promoted_tweets.")

Yes, this hierarchy applies to stats, too. The one that’s different—outside of the ads entity hierarchy—is ORGANIC_TWEET.

[LevPog]

Hello,
We are pulling spend through the twitter API and we are noticing that the country is designated as “United States” rather than the correct country of app install/impression/click.

Our analytics team mentioned that we are getting country from twitter response from API:

https://developer.twitter.com/en/docs/ads/campaign-management/api-reference/targeting-criteria

value ‘name’ is the one we are using to identify country when

{targeting_type = ‘LOCATION’ and location_type=‘COUNTRIES’}

Would you be able to help us with getting the correct country designation from the API?
Thank You

[juanshishido]

@LevPog: Thanks for the question. It does not seem specifically related to this thread, though. Please create a new post and provide some additional details around what’s going on. Include example requests and responses so we can understand the issue. See our Guidelines for Reporting Issues. Thanks.

[juanshishido]