Import Data from Facebook Ads

Use this guide to create a Facebook Ads Data Mart.

Before You Start

Check these items before you create the Data Mart:

• You have set up OWOX Data Marts.
• You have an OWOX storage, or you create one during setup.
• You can access the target ad account in Meta Ads Manager.
• You know the numeric Facebook Account ID.
• You chose an authentication method in Credentials.

For a general connector walkthrough, see Connector-based Data Mart.

Create the Data Mart

1. Click New Data Mart.
2. Enter a title.
3. Select a storage.
4. Click Create Data Mart.

If you have no storage yet, choose Create new storage in the Storage dropdown, then pick a storage type. You can add its settings later. The Data Mart cannot publish until the storage settings are valid.

Set Up the Connector

1. In Input Source, set Definition Type to Connector.
2. Choose Facebook Ads.
3. Choose your authentication method.

For OAuth, click Continue with Facebook, then sign in with a Facebook user who can access the ad account. If the button does not appear, use the Access Token method.

For manual authentication, fill in these fields:

• Access Token: paste the token from Credentials.
• App ID: enter your Meta App ID.
• App Secret: enter your Meta App Secret.

Then fill in Account IDs. Use numeric ad account IDs only, without the act_ prefix. You can find the ID in Meta Ads Manager under Account Overview. To import from multiple accounts, separate IDs with commas or semicolons. The authorized Facebook user must access every listed account.

Configure Data Import

1. Choose an endpoint. Each Data Mart imports one endpoint, so create another Data Mart for each additional endpoint.
2. Select fields, or keep the defaults.
3. Enter the target dataset, or keep the default. The connector names each table after its endpoint, for example facebook_ads_ad_account_insights.
4. Click Finish.
5. Click Publish & Run Data Mart. The first run imports from the first day of the previous month and can take several minutes.

The connector writes its tables into your storage. The field label depends on your storage, such as Dataset for BigQuery or Database for Amazon Redshift. For your storage, see Supported Storages.

For spend, clicks, impressions, conversions, and ROAS, choose Ad Account Insights.

For endpoint details, see Endpoints and Fields.

Publish & Run Data Mart stays inactive until your storage has valid settings. Open the storage, check its settings, then come back to this step. See Storage Management.

Resolve Short Links

Facebook ads often point to short links. OWOX can follow each short link and store its target next to it:

• Ad Account Insights by Link URL Asset: link_url_asset.website_url resolves into link_url_asset.parsed_url.
• Ad Creatives: object_url resolves into object_url_parsed, and link_url into link_url_parsed.

Keep the source field and its parsed field selected and enable Process Short Links under Advanced settings. OWOX selects them by default. A parsed field holds the address the short link service points to, and the original value for other links. OWOX does not request that address, so redirects on the landing site itself are not followed.

OWOX resolves links from known short link services, such as Bitly (bit.ly) and TinyURL (tinyurl.com). Links on other domains stay unchanged. Your administrator adds your own short link domains to the CONNECTOR_SHORT_LINK_DOMAINS environment variable. In OWOX Cloud, contact support to add a domain. See Environment Variables.

OWOX skips links with query parameters, such as ?utm_source=facebook, because they already point to the landing page. OWOX follows HTTP redirects only, so a short link that opens an interstitial page stays unresolved.

OWOX sends one request per distinct link and remembers the answer for 30 days, including links that do not redirect. Later runs skip remembered links. If a Data Mart has more distinct links than the memory holds, OWOX requests the extra ones on each run.

Ad Creatives rows get the parsed field on the next run, because every run re-imports them. For Ad Account Insights by Link URL Asset, rows imported earlier keep their old values until you run a backfill.

Start a Manual Run

Publish & Run Data Mart already started the first import. Without a trigger, the Data Mart does not run again. To import again, click Manual Run and choose a run type, or set a trigger. See schedule connector runs.

Schedule Automatic Runs

1. Open the Triggers tab of your Data Mart.
2. Click + Add Trigger.
3. Set Trigger Type to Connector Run.
4. Choose a schedule: Daily, Weekly, Monthly, or Interval.
5. Click Save.

Incremental Load

Choose Manual run → Incremental load.

The first incremental run imports data from the first day of the previous month through today. Each successful incremental run saves the last requested date. Later runs start from that date minus Reimport Lookback Window. This lookback refreshes recently changed Facebook Ads metrics.

Backfill

Choose Backfill (custom period) to import a specific date range.

1. Select Start Date.
2. Select End Date.
3. Click Run.

The import includes both the start date and the end date. One backfill run covers at most 31 days, so a full calendar month fits in one run. The form shows how many days your period covers and rejects a longer one before the run starts. To reload a longer history, run several backfills with consecutive periods. Start each run after the previous one finishes.

Both dates are required. The date picker does not offer future dates. The End Date must be on or after the Start Date.

Check the Result

Open Run history. The run has finished when the status shows Success.

You can query the imported tables in the dataset you selected. You can also send the data to a destination. See Destination Management and Google Sheets.

Troubleshooting

If a run fails, open Run history. Then match the Meta error with Troubleshooting.

For credential setup errors, see Credentials.

Support

1. Check Run history for the exact error.
2. Search Q&A.
3. Open an issue to report a bug.
4. Join the discussion forum.