Best Practices

Recommended setup

Start at the campaign level

Pull the Campaign entity first to get a working overview of spend and performance. Once that's confirmed working, add Ad group or Promoted tweet entities as additional sources in the same data flow.

Join metadata with metrics

X Ads API separates entity names (campaign name, tweet name) from metric data. Use two sources — one for the entity metadata, one for analytics — and join them on the ID field to get named rows in your report.

Use Append for multi-account reporting

If you manage multiple X Ads accounts, create one source per account and use Coupler.io's Append transformation to stack them into a single table. Add an account name column to tell them apart.

Data refresh and scheduling

Use daily granularity for scheduled runs

Hourly granularity returns significantly more rows and is slower to process. Reserve hourly splits for one-off analysis during campaign launches — use daily for recurring scheduled reports.

Keep date ranges under 90 days for segmented reports

When you add a segmentation dimension (especially geo or device), the number of rows multiplies quickly. Shorter date windows reduce the chance of hitting API rate limits and keep your destination tidy.

Performance optimization

Select only the metric groups you need

Each metric group adds API calls. If you only care about engagement, don't enable the video or conversion metric groups — it speeds up the data flow and avoids empty columns cluttering your output.

Split geo and device reports into separate data flows

Geographic and device segmentations are detailed enough to warrant their own data flows. Mixing them with campaign-level data in one pull makes it harder to aggregate correctly and more likely to hit rate limits.

Common pitfalls

Don't sum metrics across placements if you selected "All" for the Placement parameter. Each placement type gets its own row, so summing them double-counts your totals. Either filter to a specific placement or aggregate after deduplication.

Do

• Join Campaign metadata and analytics sources to get campaign names in your metrics report

• Verify your X Pixel and conversion tags before relying on conversion metric groups

• Test with a short date range and no segmentation first, then add complexity

Don't

• Pull hourly data over long date ranges on a schedule — it strains the API and slows your data flow

• Assume zero conversions mean no conversions — check your conversion tag setup first

• Mix segmentation dimensions (e.g., geo + device) in a single source; split them into separate sources