Implementation:Mage ai Mage ai Twitter Ads Tap Init

Knowledge Sources	Mage Integrations Twitter Ads API
Domains	Data_Integration, Twitter_Ads, Configuration
Last Updated	2026-02-09 00:00 GMT

Overview

Entry point module for the Mage Twitter Ads source connector (tap), responsible for client initialization, credential validation, discovery orchestration, and sync dispatch.

Description

This module serves as the main entry point for the Twitter Ads tap. It provides:

• build_client(config) - Factory function that creates a twitter_ads.client.Client with OAuth credentials and retry/rate-limit configuration. Configures automatic 429 handling, 10 retries with 60-second delays, and retries on status codes [400, 420, 500, 502, 503, 504].
• check_credentials(client, twitter_ads_client, account_ids) - Validates OAuth tokens by fetching accounts, then verifies each account ID is accessible.
• do_discover(reports, client, account_ids, ...) - Runs the discovery phase, generating the Singer catalog from available streams and configured reports. Supports return_streams flag for programmatic usage.
• main() - CLI entry point that parses args, validates required config keys (start_date, consumer_key, consumer_secret, access_token, access_token_secret, account_ids), creates the Twitter Ads SDK client, and dispatches to discover or sync mode.

The default request timeout is 300 seconds, configurable via request_timeout in config.

Usage

Invoked as the tap entry point, either programmatically through do_discover/build_client or via CLI through main().

Code Reference

Source Location

• Repository: mage-ai
• File: mage_integrations/mage_integrations/sources/twitter_ads/tap_twitter_ads/__init__.py
• Lines: 1-133

Signature

REQUIRED_CONFIG_KEYS = [
    'start_date', 'consumer_key', 'consumer_secret',
    'access_token', 'access_token_secret', 'account_ids'
]

def build_client(config):
def check_credentials(client, twitter_ads_client, account_ids):
def do_discover(reports, client, account_ids, logger=LOGGER, return_streams=False, selected_streams=None):
def main():

Import

from mage_integrations.sources.twitter_ads.tap_twitter_ads import build_client, do_discover

I/O Contract

Key Functions

Function	Inputs	Output	Description
build_client(config)	config dict	twitter_ads.Client	Creates authenticated Twitter Ads SDK client with retry options
do_discover(reports, client, account_ids, ...)	reports, client, account_ids, optional flags	dict or stdout	Generates Singer catalog from streams and reports
check_credentials(client, twitter_ads_client, account_ids)	client, twitter_ads_client, account_ids	None (raises on failure)	Validates OAuth tokens and account IDs

Required Configuration Keys

Key	Description
start_date	Start date for incremental sync
consumer_key	Twitter OAuth consumer key
consumer_secret	Twitter OAuth consumer secret
access_token	Twitter OAuth access token
access_token_secret	Twitter OAuth access token secret
account_ids	Comma-separated Twitter Ads account IDs

Client Configuration

The Twitter Ads SDK client is configured with:

• handle_rate_limit: True - Automatic 429 handling
• retry_max: 10 - Maximum retry attempts
• retry_delay: 60000 - 60-second retry delay (milliseconds)
• retry_on_status: [400, 420, 500, 502, 503, 504] - Retryable status codes
• retry_on_timeouts: True - Retry on timeout errors
• timeout - Configurable (default: 300 seconds)

Usage Examples

from mage_integrations.sources.twitter_ads.tap_twitter_ads import build_client, do_discover

client = build_client(config)
catalog = do_discover(
    reports=config.get('reports', {}),
    client=client,
    account_ids=config['account_ids'],
    return_streams=True,
)

Related Pages

Implements Principle

• Principle:Mage_ai_Mage_ai_Source_Configuration

Requires Environment

• Environment:Mage_ai_Mage_ai_Python_3_9_Runtime