Configure X as a data pipeline source ​

Set up X as a data pipeline source to extract and sync ad account, campaign, and analytics data from the X Ads API to your destination.

Use this guide to review the features and prerequisites, connect X as a data pipeline source, configure the pipeline, and understand the supported objects, sync modes, schema handling, sensitive data handling, and known limitations.

Features supported ​

The following features are supported when you use X as a pipeline source:

• Cloud connectivity: Connects to the X Ads API over HTTPS through https://ads-api.x.com.
• Multi-account support: Sync all ad accounts your connection can access, or select specific ad accounts by ID.
• Object-level selection: Choose from supported objects across the campaign hierarchy, creative assets, targeting, and analytics reports. Refer to Supported objects for the full list.
• Incremental sync: Most campaign hierarchy, creative, and analytics objects sync incrementally. Refer to Sync modes for more information.
• Delete tracking: Detect and mark deleted records on supported objects with a soft-delete flag in your destination. Refer to Delete tracking for more information.
• Schema drift detection and handling: Detect and apply schema changes automatically with Auto-sync new fields, or keep the schema fixed with Block new fields.
• Field-level data protection: Hash or replicate sensitive fields as is before they reach your destination.
• Configurable sync frequency: Schedule syncs on a time-based interval or with a cron expression. The minimum supported interval is 15 minutes.
• Configurable analytics windows: Set how many days of analytics history the pipeline backfills, and how many trailing days it re-pulls on every run. Refer to Configure the pipeline for more information.

Prerequisites ​

Connecting X as a data pipeline source requires:

• An X account with at least one ad account you plan to sync.
• An X Developer App approved for X Ads API access. Ads API access is gated separately from general X API access and reviewed by the X Ads API team, so approval can take time. Don't expect same-day activation. Refer to Generate an X Ads API app for setup steps.
• Credentials for OAuth 1.0a authentication: a consumer key, consumer secret, access token, and access token secret generated from your approved developer app.

Generate an X Ads API app ​

Complete the following steps to create an X Developer App, apply for Ads API access, and generate the credentials your X connection needs:

Generate a consumer key and secret ​

Complete the following steps to generate a consumer key and secret in X:

Generate an access token and secret ​

Complete the following steps to generate an access token and secret in X:

Supported connection types ​

X data pipelines support OAuth 1.0a authentication:

• OAuth 1.0a: Authenticate with a consumer key, consumer secret, access token, and access token secret from an X Developer App approved for Ads API access. You can use either an app your organization registers and gets approved directly, or credentials from a shared app already approved for Ads API access, since the connection form accepts either. These tokens don't expire or refresh automatically, unlike an OAuth 2.0 connection. Tokens remain valid until you revoke them in the X Developer Console.

Connect to X ​

Complete the following steps to connect to X:

Configure the pipeline ​

Complete the following steps to configure X as your data pipeline source:

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

Supported objects ​

X data pipelines sync data from the X Ads API (version 12). The following tables list the supported objects, grouped by category. Each object syncs as a separate table in your destination:

Account and campaign hierarchy ​

The following objects mirror the X ad hierarchy: an Accounts record is the parent of Funding Instruments and Campaigns, which are the parent of Line Items, which are the parent of Promoted Tweets and Promoted Accounts. Line Item Placements, Line Item Categories, Campaign Reason, and Funding Instrument Reason are array fields on their parent record, normalized into their own tables for relational modeling.

Creative assets ​

The following objects hold creative content and rich-media assets referenced by promoted tweets and line items:

Promoted Tweet Content re-fetches tweet text and media referenced by your Promoted Tweets and Scheduled Promoted Tweets records on every run, so its row count depends on those objects.

Targeting and audiences ​

The following objects define how line items target X users:

Custom Audiences syncs audience metadata only, such as name, size, and type. X requires audience member lists, such as emails, phone numbers, and device IDs, to be hashed before they reach X. Workato doesn't extract this member data.

Scheduled content ​

The following objects support scheduling tweets and video call-to-actions ahead of publication:

Scheduled Tweets doesn't return a delete flag. X exposes cancellation instead through a status column on each record.

Account administration and reference data ​

Referenced User Profiles is an enrichment table of public X profile data for any user ID referenced by your Promoted Accounts records.

Performance analytics ​

The following objects each return daily performance metrics for one entity level, such as account, funding instrument, campaign, line item, promoted tweet, or promoted account:

Segmented performance analytics ​

X data pipelines also break out the same daily performance metrics by an additional dimension, such as age, gender, platform, or conversion tag. Age, gender, and platform segmentation are available at every entity level listed in the previous sections. Conversion tag segmentation is available only for campaign, line item, promoted tweet, and promoted account, because those are the only levels that support the underlying web-conversion metric group.

Segmented values aren't expected to sum exactly to the equivalent non-segmented totals. This is expected behavior on the X platform, not a data quality issue.

Reach and average frequency ​

These objects return unique-reach and average-frequency metrics rather than the standard performance metrics in Performance analytics. Refer to Limitations for the maximum date range per sync.

Sync modes ​

X data pipelines support full sync and incremental sync. The sync mode is configured per object when you add it to your pipeline.

Full sync ​

A full sync re-reads the complete record set for an object on every run and overwrites the destination table. Media Library, Promoted Tweet Content, Scheduled Tweets, and Referenced User Profiles use full sync, because X API doesn't expose a reliable modified-time signal for these objects.

Incremental sync ​

An incremental sync extracts only the records that changed since the last run. Most campaign hierarchy, creative, targeting, and administration objects use the X updated_at field as a cursor.

Analytics and reach objects use a different mechanism, because X metrics recalculate over time and aren't a row-level resource. On each run, the pipeline extracts from the last successful sync date forward to the current time, and uses the Analytics backfill window to size the initial historical pull. Reach & Average Frequency objects re-pull their full configured date window instead. Refer to Configure the pipeline for the analytics window settings.

Refer to the Supported objects tables to see the sync mode for each object.

Delete tracking ​

For objects marked "Yes (soft)," X returns a deleted flag directly on each record, and Workato reflects it in your destination.

Promoted Tweet Content and Referenced User Profiles don't support delete tracking, because they're re-fetched by reference from their parent objects instead of listed independently. Scheduled Tweets also doesn't return a delete flag. X expresses cancellation through a status column instead. Analytics and reach objects don't support delete tracking either, because a performance metric row recalculates on every query and isn't persisted with its own lifecycle. Metrics for deleted or paused parent entities remain fully queryable.

Schema and data type handling ​

The following considerations apply to schema and data types when you sync data from X:

Monetary amounts ​

Budget and billed-charge fields are expressed in micros of the account's local currency, for example, 1,000,000 micros = 1 unit of currency. Workato stores these values as integers and doesn't convert them at ingestion time.

Timestamps and account timezone ​

Analytics objects align daily metrics to midnight in the ad account's own timezone, not UTC, then store the resulting instant as UTC. For example, a US Pacific-time account's 2026-01-05 row stores as 2026-01-05T08:00:00Z.

Nested and array fields ​

X doesn't have user-defined custom fields. Workato handles the following array and nested fields:

• Line Items.placements and Line Items.categories store as JSON string columns on Line Items, and Workato also expands them into the Line Item Placements and Line Item Categories tables for relational modeling.
• Campaigns.reasons_not_servable stores as a JSON string column on Campaigns, and Workato also expands it into the Campaign Reason table.
• Funding Instruments.reasons_not_able_to_fund stores as a JSON string column on Funding Instruments, and Workato also expands it into the Funding Instrument Reason table.
• Cards.components stores as a JSON string column with no equivalent child table.
• Conversion metrics on analytics objects, such as web conversion, mobile conversion, and lifetime value, store as JSON string columns instead of flattening.

Video metric definitions ​

X redefined video_total_views to mean 100% in view for 3 or more seconds, or a manual play-button click. The prior definition remains available as a separate video_3s100pct_views column on the same analytics objects. Use the column that matches the definition you need. Don't assume video_total_views carries its original meaning.

Synthetic columns ​

Workato adds the following synthetic column to destination tables for objects with delete tracking:

Sensitive data handling ​

X objects can contain personally identifiable information (PII). The following objects commonly contain sensitive fields:

Custom Audiences doesn't expose individual audience members. X requires member lists to already be hashed by the uploader, and Workato doesn't extract that member-level data at all.

Use the Hash option in field-level data protection during pipeline configuration to protect PII before it reaches your destination. Refer to the Configure the pipeline steps for more information.

Limitations ​

The following limitations apply when you use X as a data pipeline source:

Analytics require completed advertiser verification ​

Analytics and reach objects return zero rows until your ad account completes the X advertiser verification in Ads Manager. Campaigns can be active and budget-valid and still not produce delivery metrics until verification finishes.

Reach and average frequency window is capped at 7 days ​

Reach & Average Frequency objects reject any request window longer than 7 days. The pipeline re-pulls a rolling 7-day window on every run for these objects.

Historical analytics backfill is limited per job ​

The X Ads API rejects an analytics job that spans more than 90 days of history and 45 days for segmented objects. Don't set the Analytics backfill window field higher than these limits, or the sync fails. Refer to Configure the pipeline for more information.

Metro-level segmentation is not supported ​

X data pipelines support age, gender, platform, and conversion-tag segmentation. Metro-level (Nielsen designated market area) segmentation isn't available.

Minimum sync frequency ​

The minimum supported sync interval is 15 minutes.