Twitter Ads

The Twitter Ads Connector provides automated access to Twitter reports for Ads, Campaigns Report, Funding Instruments, and Line Items.

Prerequisites

The Twitter ads connector uses Oauth to authenticate.

In the Key Manager, add a Key.

Choose the “Twitter” credential type.

Supply a name and then hit connect to set the OAuth connection.

Scheduling

The Twitter Ads connector can be scheduled to ingest data on an hourly basis.

See Hourly Scheduling for more information.

Twitter Ads Report

type = twitter:ads

Parameters

account_ids list of strings
required
Identifier for the leveraged account, must be associated with the authenticated user
api_version string
required
Valid values for api_version field are 9, 10, 11
entities list of strings
required
The entity type to retrieve data for; See Twitter’s Developer Platform documentation for possible entity enum values.
entity_limit integer
optional
granularity integer
required
Specifies how granularity of the retrieved data should be. Parameters can be HOUR or DAY.
metric_groups list of strings
required
Specific metrics that should be returned. See Twitter’s Developer Platform documentation for possible metric_groups enum values.
placements list of strings
required
Scopes the retrieved data to a particular placement. See Twitter’s Developer Platform documentation for possible placement enum values.
segmentation string
required
Specifies how the retrieved data should be segmented. See Twitter’s Developer Platform documentation for possible segmentation_type enum values.

Sample Switchboard Script

download twitter_751p3v_raw from {
    type: "twitter:ads";
    key: "twitter_key";

    repull_days: 30;

    // The timezone here must match the timezone for the account on Twitter
    account_ids: ["12345"];
    timezone: "America/New_York";


    entities: ["LINE_ITEM"];
    segmentation: "LOCATIONS";

    metric_groups: [
        "BILLING",
        "ENGAGEMENT",
        "LIFE_TIME_VALUE_MOBILE_CONVERSION",
        "MEDIA",
        "MOBILE_CONVERSION",
        "VIDEO",
        "WEB_CONVERSION"
    ];

    placements: ["ALL_ON_TWITTER", "PUBLISHER_NETWORK"];

    // This may be "DAY" or "HOUR".
    granularity: "DAY";
} using {
    request: {
        params: {
            entity: string not nullable;
            start_time: datetime not nullable;
            end_time: datetime not nullable;
            placement: string not nullable;
            granularity: string not nullable;
            segmentation_type: string;
            platform: string;
            country: string;
        };
    };
    data: [
        {
            id: string not nullable;
            id_data: [
                {
                    segment: {
                        segment_name: string;
                    };
                    metrics: {
                        impressions: [integer];
                        follows: [integer];
                        engagements: [integer];
                        clicks: [integer];
                        likes: [integer];
                        retweets: [integer];
                        replies: [integer];
                        video_total_views: [integer];
                        video_views_25: [integer];
                        video_views_50: [integer];
                        video_views_75: [integer];
                        video_views_100: [integer];
                        video_cta_clicks: [integer];
                        video_mrc_views: [integer];
                        billed_charge_local_micro: [integer];
                        conversion_purchases: json;
                        conversion_sign_ups: json;
                        conversion_site_visits: json;
                        conversion_downloads: json;
                        conversion_custom: json;
                        mobile_conversion_spent_credits: json;
                        mobile_conversion_installs: json;
                        mobile_conversion_content_views: json;
                        mobile_conversion_add_to_wishlists: json;
                        mobile_conversion_checkouts_initiated: json;
                        mobile_conversion_reservations: json;
                        mobile_conversion_tutorials_completed: json;
                        mobile_conversion_achievements_unlocked: json;
                        mobile_conversion_searches: json;
                        mobile_conversion_add_to_carts: json;
                        mobile_conversion_payment_info_additions: json;
                        mobile_conversion_re_engages: json;
                        mobile_conversion_shares: json;
                        mobile_conversion_rates: json;
                        mobile_conversion_logins: json;
                        mobile_conversion_updates: json;
                        mobile_conversion_levels_achieved: json;
                        mobile_conversion_invites: json;
                        mobile_conversion_key_page_views: json;  
                                                
                    };

                }
            ];
        }
    ];
};

Twitter Campaigns Report

type = twitter:campaigns

Parameters

account_ids list of strings
required
Identifier for the leveraged account, must be associated with the authenticated user.
api_version string
required
Valid values for api_version field are 9, 10, 11

Sample Switchboard Script

download twitter_campaigns_raw from {
    period_hours: 2;
    type: "twitter:campaigns";
    key: "twitter_key";
    account_ids: [
        "12345"
    ];
} using {
    "id": string;
    "name": string;
    "start_time": datetime;
    "end_time": datetime;
    "servable": boolean;
    "daily_budget_amount_local_micro": integer;
    "total_budget_amount_local_micro": integer;
    "duration_in_days": integer;
    "standard_delivery": boolean;
    "entity_status": string;
    "frequency_cap": string;
    "currency": string;
    "created_at": datetime;
    "updated_at": datetime;
    "deleted": boolean;
    funding_instrument_id: string;
};

Twitter Funding Instrument Report

type = twitter:funding_instruments

Parameters

account_ids list of strings
required
Identifier for the leveraged account, must be associated with the authenticated user.
api_version string
required
Valid values for api_version field are 9, 10, 11

Sample Switchboard Script

download twitter_funding_instruments_raw from {
    period_hours: 2;
    type: "twitter:funding_instruments";
    key: "twitter_key";
    account_ids: [
        "12345"
    ];
} using {
	id: string;
	description: string;
	end_time: datetime;
	start_time: datetime;
	created_at: datetime;
	updated_at: datetime;
	entity_status: string;
	currency: string;
	account_id: string;
	io_header: string;
	type: string;
	able_to_fund: boolean;
	deleted: boolean;
	credit_limit_local_micro: integer;
	credit_remaining_local_micro: integer;
	funded_amount_local_micro: integer;
};

Twitter Line Items Report

type = twitter:line_items

Parameters

account_ids list of strings
required
Identifier for the leveraged account, must be associated with the authenticated user.
api_version string
required
Valid values for api_version field are 9, 10, 11.

Sample Switchboard Script

downlaod twitter_line_items_raw from {
    period_hours: 2;
    type: "twitter:line_items";
    key: "twitter_key";
    key: "twitter_key";
    account_ids: [
        "12345"
    ];
} using {
    "id": string;
    "name": string;
    "campaign_id": string;
    "start_time": datetime;
    "end_time": datetime;
    "servable": boolean;
    "daily_budget_amount_local_micro": integer;
    "total_budget_amount_local_micro": integer;
    "currency": string;
    "created_at": datetime;
    "updated_at": datetime;
    "bid_type": string;
    "advertiser_user_id": integer;
    "advertiser_domain": string;
    "bid_unit": string;
    "optimization": string;
    "deleted": boolean;
};