Twitter Ads integration summary

Stitch’s Twitter Ads integration:

  • Replicates core object data using the Twitter Ads API v.7. Refer to the Schema section for a list of objects available for replication.
  • Supports configuring custom reports using Twitter’s Analytics API

Twitter Ads feature snapshot

A high-level look at Stitch's Twitter Ads (v1) integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release status Supported by

Stitch

Stitch plan

Standard

API availability

Available

Singer GitHub repository

singer-io/tap-twitter-ads

REPLICATION SETTINGS
Anchor Scheduling

Supported

Advanced Scheduling

Supported

Table-level reset

Unsupported

Configurable Replication Methods

Unsupported

DATA SELECTION
Table selection

Supported

Column selection

Supported

Select all

Supported

TRANSPARENCY
Extraction Logs

Supported

Loading Reports

Supported

Connecting Twitter Ads

Twitter Ads setup requirements

To set up Twitter Ads in Stitch, you need:

  • To have access to the Twitter Ads accounts you want to replicate data from.


Step 1: Retrieve account ID

  1. Login to your Twitter Ads account.
  2. Select the ads account that you’d like to use.
  3. Click your account icon upper right corner of the screen.
  4. Click Settings in the dropdown menu.
  5. Copy your account ID and keep it readily available for the next step.

Note: If you would like to add multiple ads accounts for this integration, repeat the above steps for each account.

Step 2: Add Twitter Ads as a Stitch data source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Twitter Ads icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Twitter Ads” would create a schema called stitch_twitter_ads in the destination. Note: Schema names cannot be changed after you save the integration.

  5. In the Account IDs field, paste the account ID you copied from Step 1. If you’re adding multiple accounts IDs, format them as a comma-delimited list. For example: accountId1, accountId2
  6. Optional: In the Attribution Window field, enter the number of days you want to use as a lookback period for conversion reporting to stabilize. Custom report tables use this value during Extraction.
  7. Optional: Check the with deleted box if you want to include deleted records in the extraction Stitch performs.
  8. In the Country Codes field, enter a comma-separated list of the ISO alpha-2 country codes for each country you want to include in segmentation and targeting.

    For example: A list of US, DE, IE corresponds to United States, Germany, Ireland.

    Note: This field is required to use some segment types in custom reports.

Step 3: Configure reports

Stitch’s Twitter Ads integration supports the configuration of custom reports. For each report configured in the Your Reports section, a table will display in the Tables to Replicate tab as available for selection.

Refer to the Table reference for an example of a custom report table.

Create a new report

To add a report, click the + Configure new report link. For each report you configure, you’ll define the following parameters:

  • Report Name: A name for the report, which is used to create the name of its corresponding destination table
  • Entity: The Twitter Ads entity (object) to report on. The entity you select determines the metrics (columns) available for selection and the segments you can apply to those metrics. Refer to the Custom report options compatibility reference for more info.
  • Segment: A segment to apply to the entity’s available metrics. Note: Some entity and segment combinations may be incompatible. Refer to the Segment compatibility reference for more info.
  • Granularity: The granularity of the report data. Possible options are DAY, HOUR, and TOTAL.

Remove a report

To remove a report, click the - Remove this report link.

Note: Removing a report will not remove the corresponding table or its data from your destination.

Step 4: Define the historical replication start date

The Sync Historical Data setting defines the starting date for your Twitter Ads integration. This means that:

  • For tables using Key-based Incremental Replication, data equal to or newer than this date will be replicated to your destination.
  • For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your destination.

Change this setting if you want to replicate data beyond Twitter Ads’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 5: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Twitter Ads integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 6: Set objects to replicate

The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

For Twitter Ads integrations, you can select:

  1. Individual tables and columns

  2. All tables and columns

Click the tabs to view instructions for each selection method.

  1. In the integration’s Tables to Replicate tab, locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
  1. Click into the integration from the Stitch Dashboard page.
  2. Click the Tables to Replicate tab.

  3. In the list of tables, click the box next to the Table Names column.
  4. In the menu that displays, click Track all Tables and Fields:

    The Track all Tables and Fields menu in the Tables to Replicate tab

  5. Click the Finalize Your Selections button at the bottom of the page to save your data selections.

Initial and historical replication jobs

After you finish setting up Twitter Ads, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


Twitter Ads replication

In this section:

Extraction

This section provides a high-level look at extraction, but you can check out the sync review on Google Docs for a more technical look at this process.

For every table set to replicate, Stitch will perform the following during Extraction:

Discovery

During Discovery, Stitch will:

Determining table availability

At the start of each replication job, Stitch performs a structure sync. During this phase, Stitch detects the objects available for replication.

There are two types of tables for Twitter Ads:

  • Core object tables: These are tables that aren’t created using the Custom reports feature in the integration’s settings page. Table availability depends on the Twitter Ads Singer tap, which powers Stitch’s integration. The tap contains a JSON schema for each available table.

    The Table reference section of this guide lists the tables currently available for replication, as well as info about how they replicate.

  • Custom report tables: These are tables that are created using the Custom reports feature in the integration’s settings page. Table availability depends on configuration of the report in the integration’s settings page. Note: Custom report tables must also be set to replicate in the Tables to Replicate tab - Stitch won’t automatically replicate them.

    Refer to the Table reference for an example of a custom report table.

Determining column availability

Column availability is dependent upon the type of table:

  • Core Object tables: Column availability is determined by the JSON schema backing the table in the Singer tap.
  • Custom report tables: Column availability is determined by the Entity selected during report configuration. Each entity in Twitter Ads is compatible with one or more metric groups. Each metric in a metric group corresponds to a column available for replication.

    For example: If the entity is compatible with the BILLING metric group, you’d see billed_engagements and billed_charge_local_micro columns available for replication.

    Refer to the Entity and metric group compatibility reference for more info.

Data replication

After discovery is completed, Stitch will move onto extracting data for the tables and columns you set to replicate.

How Stitch extracts data depends on the type of table being replicated:

  • Core object tables: For these tables, extraction depends on the type of Replication Method the table uses. Refer to the Table reference for the Replication Method each table uses.

  • Custom report tables: Custom report tables replicate using Key-based Incremental Replication and the Attribution Window you define during setup. Attribution Windows are used in conjunction with Replication Keys to determine where Stitch should begin extraction for a table during each extraction job.

Loading

How data replicated from an Twitter Ads integration is loaded into your destination depends on two factors:

  1. The type of table being loaded:
  2. If your destination supports upserts, or updating existing rows. For destinations that support upserts, Stitch uses Primary Keys to de-dupe data during loading. Primary Keys are used to identify unique rows within a table and ensure that only the most recently updated version of that record appears in your destination.

Note: For Append-Only destinations, data will be loaded in an Append-Only manner, regardless of the table type.


Twitter Ads table reference

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get accounts

The accounts table contains info about the advertising-enabled accounts the user authenticating the integration has access to.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get account media for an account

The account_media table contains info about the account media associated with an account.


advertiser_business_categories

Replication Method :

Full Table

Primary Key :

id

API endpoint :

Get advertiser business categories for an account

The advertiser_business_categories table contains info about the advertiser business categories associated with an advertiser’s ad groups.

id
STRING

iab_categories
ARRAY

name
STRING


Replication Method :

Full Table

Primary Key :

currency

API endpoint :

Get bidding rules

The bidding_rules table contains info about the bidding rules for currencies.

currency
STRING

maximum_cpe_bid_local_micro
INTEGER

minimum_cpe_bid_local_micro
INTEGER

minimum_denomination
INTEGER


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get campaigns for an account

The campaigns table contains info about the campaigns associated with an account.


cards_image_app_download

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get image app download cards for an account

The cards_image_app_download table contains info about image app download cards associated with an account.


cards_image_conversation

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get image conversation cards for an account

The cards_image_conversation table contains info about image conversation cards associated with an account.


cards_image_direct_message

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get image direct message cards for an account

The cards_image_direct_message table contains info about the image direct message cards associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get poll cards for an account

The cards_poll table contains info about poll cards associated with an account.


cards_video_app_download

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get video app download cards for an account

The cards_video_app_download table contains info about the video app download cards associated with an account.


cards_video_conversation

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get video conversation cards for an account

The cards_video_conversation table contains info about the video conversation cards associated with an account.


cards_video_direct_message

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get video direct message cards for an account

The cards_video_direct_message table contains info about the video direct message cards associated with an account.


cards_video_website

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get video website cards for an account

The cards_video_website table contains info about the video website cards associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get website cards for an account

The cards_website table contains info about the website cards associated with an account.


content_categories

Replication Method :

Full Table

Primary Key :

id

API endpoint :

Get content categories

The content_categories table contains info about the content categories used as targeting criteria for ad groups.

id
STRING

iab_categories
ARRAY

name
STRING


EXAMPLE_CUSTOM_REPORT

Replication Method :

Key-based Incremental

Replication Key :

end_time

Primary Key :

_sdc_dimensions_hash_key

Official docs :

Official Docs

Loading Behavior:

Append-Only

This is an example of a table created from a custom report configured in the integration’s settings page.

Metric columns in report tables depend on the entity selected for the report.

When data is extracted for reports, Stitch uses the Attribution Window defined in the integration’s settings.

_sdc_dimensions_hash_key
STRING

Applicable only to Twitter Ads integrations, this column is a a Stitch-generated MD5 hash that should be used as a Primary Key in tables created using the Custom reports feature.

The hash consists of a UTF-8 encoded JSON list containing of the report’s dimensions.

end_time
DATE-TIME

METRICS_YOU_SELECT
VARIES

The available metrics depend on the entity you select for the report. Refer to the Entity and metric group compatibility reference for more info.

account_id
STRING

Reference:

country
STRING

entity
STRING

The entity selected for the report. Refer to the Entity and metric group compatibility reference for more info.

Possible values are:

  • ACCOUNT

  • CAMPAIGN

  • FUNDING_INVESTMENT

  • LINE_ITEM

  • MEDIA_CREATIVE

  • ORGANIC_TWEET

  • PROMOTED_ACCOUNT

  • PROMOTED_TWEET

entity_id
STRING

The name of the entity selected for the report.

granularity
STRING

The granularity selected for the report. Possible values are:

  • HOUR
  • DAY
  • TOTAL

placement
STRING

platform
STRING

report_name
STRING

segment_name
STRING

segment_value
STRING

segmentation_type
STRING


funding_instruments

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get funding instruments for an account

The funding_instruments table contains info about the funding instruments associated with an account.


Replication Method :

Full Table

Primary Key :

id

API endpoint :

Get IAB categories

The iab_categories table contains info about the app categories associated with ad groups.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get line items for an account

The line_items table contains info about the line items (ad groups) associated with an account.

id
STRING

Reference:

updated_at
DATE-TIME

account_id
STRING

Reference:

advertiser_domain
STRING

advertiser_user_id
INTEGER

automatically_select_bid
BOOLEAN

bid_amount_local_micro
INTEGER

bid_type
STRING

bid_unit
STRING

campaign_id
STRING

Reference:

categories
ARRAY

value
STRING

line_items (table), categories (attribute)

charge_by
STRING

created_at
DATE-TIME

creative_source
STRING

currency
STRING

deleted
BOOLEAN

end_time
DATE-TIME

entity_status
STRING

name
STRING

objective
STRING

optimization
STRING

placements
ARRAY

value
STRING

line_items (table), placements (attribute)

primary_web_event_tag
STRING

product_type
STRING

start_time
DATE-TIME

target_cpa_local_micro
INTEGER

total_budget_amount_local_micro
INTEGER

tracking_tags
ARRAY

value
STRING

line_items (table), tracking_tags (attribute)

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get line item apps for an account

The line_item_apps table contains info about the apps associated with line items associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get media creatives for an account

The media_creatives table contains info about the media creatives associated with an account.


preroll_call_to_actions

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get preroll call to actions for an account

The preroll_call_to_actions table contains info about the preroll call-to-actions associated with line items (ad groups) associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get promotable users for an account

The promotable_users table contains info about the promotable users associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get promoted accounts

The promoted_accounts table contains info about the promoted accounts associated with line items (ad groups) associated with an account.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get promoted tweets

The promoted_tweets table contains info about references to Tweets associated with line items (ad groups) associated with an account.


scheduled_promoted_tweets

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get scheduled promoted Tweets

The scheduled_promoted_tweets table contains info about the scheduled promoted Tweets associated with an account.


tailored_audiences

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Get Tailored Audiences

The tailored_audiences table contains info about the Tailored Audiences associated with an account.


targeting_app_store_categories

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get app store categories

The targeting_app_store_categories table contains info about the app store targeting categories associated with promoted products.

targeting_value
STRING

name
STRING

os_type
STRING

targeting_type
STRING


targeting_conversations

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get targeting conversations

The targeting_conversations table contains info about the conversation-based targeting criteria for Promoted Products.

targeting_value
STRING

conversation_type
STRING

name
STRING

targeting_type
STRING


targeting_criteria

Replication Method :

Full Table

Primary Key :

id : line_item_id

API endpoint :

Get targeting criteria for an account

The targeting_criteria table contains info about the targeting criteria associated with an account.


targeting_devices

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get targeting device criteria

The targeting_devices table contains info about the device-based targeting criteria for Promoted Products.

targeting_value
STRING

manufacturer
STRING

name
STRING

os_type
STRING

targeting_type
STRING


targeting_interests

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get interest targeting criteria

The targeting_interests table contains info about the interest-based targeting criteria for Promoted Products.

targeting_value
STRING

name
STRING

targeting_type
STRING


targeting_languages

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get language targeting criteria

The targeting_languages table contains info about the language-based targeting criteria for Promoted Products.

targeting_value
STRING

name
STRING

targeting_type
STRING


targeting_locations

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get targeting location criteria

The targeting_locations table contains info about location-based targeting criteria for Promoted Products. According to Twitter Ads’s documentation, geo-targeting is available for Promoted Accounts and Tweets at the country, state/region, city, and postal code levels.

targeting_value
STRING

country_code
STRING

location_type
STRING

name
STRING

targeting_type
STRING


targeting_network_operators

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get network operator targeting criteria

The targeting_network_operators table contains info about network operator-based targeting criteria for Promoted Products.

targeting_value
STRING

country_code
STRING

name
STRING

targeting_type
STRING


targeting_platforms

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get platform targeting criteria

The targeting_platforms table contains info about platform-based targeting criteria for Promoted Products.

targeting_value
STRING

name
STRING

targeting_type
STRING


targeting_platform_versions

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get platform version targeting criteria

The targeting_platform_versions table contains info about mobile OS-version based targeting criteria for Promoted Products.

targeting_value
STRING

name
STRING

number
STRING

os_type
STRING

targeting_type
STRING


targeting_tv_markets

Replication Method :

Full Table

Primary Key :

locale

API endpoint :

Get TV market targeting criteria

The targeting_tv_markets table contains info about TV markets where TV shows can be targeted. Use the targeting_tv_shows table for info about individual TV shows.

locale
STRING

country_code
STRING

name
STRING


targeting_tv_shows

Replication Method :

Full Table

Primary Key :

targeting_value

API endpoint :

Get TV show targeting criteria for a TV market

The targeting_tv_shows table contains info about TV-show based targeting criteria for Promoted Products.

targeting_value
STRING

genre
STRING

locales
ARRAY

The TV market locales the TV show is associated with. Use these values to join records from this table to the targeting_tv_markets table.

In the format language-country, these values will match the targeting_tv_markets.locale column. For example: If language: en and country: US, construct a the values as language-country, or en-US in this case, to join to the targeting_tv_markets table where locale: en-US.