Skip to content
Book a demo

Connect documentation

All documentation
Documentation

X Ads: Setup guide

On this page

This guide explains how to collect data from Twitter Ads.

Introduction

For a list of the fields that you can collect from Twitter Ads, see Twitter Ads.

You can retrieve information for cards created through Twitter Ads API or ads.twitter.com. You cannot retrieve information for cards created through the Twitter user interface.

Limitations

Collecting data from Twitter Ads comes with the following limitations:

  • Some API endpoints are limited to a maximum date range of 90 days per request. To fetch longer periods of historical data, split your fetch into multiple 30-day date windows.

Prerequisites

Before you start collecting data from Twitter Ads, perform all of the following actions:

  • Ensure that the Twitter user who sets up the authorization has one of the following roles:

    • Ad Manager

    • Account Administrator

Creating a datastream to collect data from Twitter Ads

The basics of creating a datastream to collect data from any data source are explained in our guide to Collecting data in Adverity. This guide contains information about the specific steps to create a datastream to fetch data from Twitter Ads.

Authorization: Allow Adverity to access Twitter Ads

  1. If you choose Access using your credentials or Access using someone else’s credentials, in Set up or edit Accounts, you or the person granting access must choose one of the following options:

    • Choose Grant access to all items, including those created in the future to give Adverity Accounts to access all existing items and all items created in the future.

    • Choose Select specific items to which you want to grant access to only give Adverity Accounts to access the selected items. Adverity will not automatically have access to items created in the future. You will need to grant Adverity access to any items created in the future.

Configuration: Choose the data you want to collect from Twitter Ads

To choose what data to collect and customize the Twitter Ads datastream configuration, follow these steps:

  1. (Optional) Rename your datastream.

  2. In Accounts, select the accounts for which to collect data. You can choose to include or exclude specific items, or select all items.

  3. In Report type, select the type of data to collect from Twitter Ads. The fields you need to configure in the following steps differ according to the report type you select.

  4. In Level, select the type of data to collect from Twitter Ads. The configuration options below may change depending on the selected level.

  5. In Metadata type, select the type of the metadata that you want to collect.

  6. In Date filter, select the field that you want to use to define the fetch date range.

  7. In Accounts, select the accounts to include in the report.

  8. In Metrics and Dimensions, change the list of fields that you want to see in your data extract.

  9. In Placement, select the ad placement type. If you do not select any items in a drop-down list, Adverity collects data for all items in the drop-down list.

  10. In Granularity, select the time unit in which you want to retrieve your data.

  11. Select the Include mentions and replies checkbox to collect data for mentions and replies to your tweets.

  12. In Campaigns, select the campaigns for which to collect data. If you do not select any items in a drop-down list, Adverity collects data for all items in the drop-down list.

  13. Select the Include inactive campaigns checkbox to include campaigns older than 90 days.

  14. Select the Include empty rows checkbox to include the rows for which all metrics are zero.

  15. In Segmentation, select how to segment your data.

  16. Select the Media screenshots enabled checkbox to capture media screenshots.

  17. In Age, select the age buckets for which to collect data.

Troubleshooting

I see a timezone error message when fetching data from Twitter Ads

The Expect time to be midnight in the account's local timezone for day granularity error message appears because you are trying to fetch data for a date range over 90 days.

To resolve this issue, fetch data for a date range shorter than 90 days.

My ad name has not been updated in the data I have collected from Twitter Ads

If you have updated the name of an ad in the Twitter Ads UI but the new name does not appear in the data collected from Twitter Ads, follow these steps to update the name:

  1. Synchronize the metadata for the authorization you are using to collect the data.

  2. Delete any cached tweets.

  3. Wait until the update queue is empty, which means the metadata has been synchronized.

  4. Fetch your data again to check that the name has been updated.

I cannot collect card data from Twitter Ads

The Twitter user who authorizes Adverity to access Twitter Ads must have an Ad Manager or Account Administrator role in order to fetch the card_name and website_card_url fields:

To collect data about these card fields, follow these steps:

  1. Update the permissions of the Twitter user who used their credentials to grant the authorization to one of the following roles:

    • Ad Manager

    • Account Administrator

  2. Update the authorization to Twitter Ads. For more information, see Updating an authorization.

  3. Contact your Adverity Customer Success manager. Our Engineering Team needs to manually sync all tweet data (including card data) within the Adverity platform.

  4. Collect data from Twitter Ads using the updated authorization. If these fields are still not present in your data extract, contact the Adverity Support team.

Tips and best practices

Configuring screenshot capture for Twitter Ads

To access the Twitter Ads configuration page and enable screenshot capture, follow these steps:

  1. Go to the Datastreams page.

  2. Open the Twitter Ads datastream by clicking on its name.

  3. In the top navigation panel, click Settings.

  4. In the General section of the page, fill in the following fields:

    Media Screenshots enabled

    To take screenshots of your ads, select this checkbox and make sure Dimensions contains the field tweet_id.

    The screenshots are saved in the same storage as the Twitter Ads data extracts.

Previewing an image

To preview an image, collect the following dimensions:

  • entities_expanded_urls for external links

  • media_url for native/uploaded objects

What’s next?

Advanced Twitter Ads tips

For advanced configuration and best practices, see Advanced Twitter Ads tips.