Schedule a Facebook Ads transfer

The BigQuery Data Transfer Service for Facebook Ads lets you automatically schedule and manage recurring load jobs from Facebook Ads into BigQuery.


Facebook Ads transfers are subject to the following limitations:

  • The minimum interval time between recurring Facebook Ads transfers is 15 minutes. The default interval for a recurring transfer is 24 hours.
  • The BigQuery Data Transfer Service for Facebook Ads only supports a fixed set of tables. Custom reports aren't supported.
  • Facebook Ads transfers have a maximum duration of six hours. A transfer fails if it takes longer than this maximum duration.
  • Incremental transfers aren't supported.
  • The BigQuery Data Transfer Service supports the transfer of data from up to one day (yesterday) to the AdInsights and AdInsightsActions tables.

Before you begin

The following sections describe the steps that you need to take before you create a Facebook Ads transfer.

Facebook Ads prerequisites

Ensure that you have the following Facebook Ads information when creating a Facebook Ads transfer.

Facebook Ads parameters Description
clientID The app ID name for the OAuth 2.0 client.
clientSecret The app secret for the OAuth 2.0 client.
refreshToken The long-lived user access token, also known as a refresh token.

To obtain a clientID and clientSecret, perform the following steps:

  1. Create a Facebook developer app with the app type Business.
  2. In the Facebook App dashboard, click App Settings > Basic and find the app ID and app secret that correspond to the app.

To obtain a long-lived user access token, also known as a refresh token, perform the following steps:

  1. In the Google Cloud console, proceed with the steps to create a Facebook Ads transfer.

  2. In the Data Source Details section, copy the redirect URI listed after the Refresh Token field.

    Copy the redirect URI

  3. Click the Facebook App dashboard, then click Set up in the Facebook login for Business section.

    Configure the settings for Facebook Login for Business

  4. In the Settings page, enter the redirect URL in the Valid OAuth Redirect URIs field and click Save.

  5. Return to the Google Cloud console. In the Data Source Details section, click Authorize. You will be redirected to a Facebook authentication page.

    Generate a long-lived user access token

  6. Select the Facebook developer app to authorize the account that connects with the BigQuery Data Transfer Service.

  7. Once complete, click Got it to return to the Google Cloud console. The long-lived access token is now populated in the transfer configuration.

Alternatively, you can generate a long-lived user access token using the Graph API. The ads_management, ads_read, and business_management permissions are required for a valid token for the transfer.

Long-lived user access tokens expire after 60 days.

BigQuery prerequisites

Required BigQuery roles

To get the permissions that you need to create a transfer, ask your administrator to grant you the BigQuery Admin (roles/bigquery.admin) IAM role. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to create a transfer. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create a transfer:

  • bigquery.transfers.update on the user
  • bigquery.datasets.get on the target dataset
  • bigquery.datasets.update on the target dataset

You might also be able to get these permissions with custom roles or other predefined roles.

Create a Facebook Ads data transfer

Select one of the following options:


  1. In the Google Cloud console, go to the BigQuery Studio page.

    Go to BigQuery Studio

  2. Click Data transfers > Create a transfer.

  3. In the Source type section, for Source, select Facebook Ads.

  4. In the Transfer config name section, for Display name, enter a name for the transfer.

  5. In the Schedule options section, do the following:

    • In the Repeat frequency list, select an option to specify how often this transfer runs. To specify a custom repeat frequency, select Custom. If you select On-demand, then this transfer runs when you manually trigger the transfer.

    • If applicable, select either Start now or Start at set time and provide a start date and run time.

  6. In the Destination settings section, for Dataset, select the dataset you created to store your data.

  7. In the Data source details section, do the following:

    • For Client ID, enter the app ID.
    • For Client secret, enter the app secret.
    • For Refresh token, enter the long-lived user access token ID by clicking Authorize.

    For information about retrieving these values, see Facebook Ads Prerequisites.

  8. Optional: In the Service Account menu, select a service account from the service accounts associated with your Google Cloud project. The selected service account must have the required roles to run this transfer.

    If you signed in with a federated identity, then a service account is required to create a transfer. If you signed in with a Google Account, then a service account for the transfer is optional.

    For more information about using service accounts with data transfers, see Use service accounts.

  9. Optional: In the Notification options section, do the following:

    • To enable email notifications, click the Email notification toggle. When you enable this option, the transfer administrator receives an email notification when a transfer run fails.
    • To enable Pub/Sub transfer run notifications for this transfer, click the Pub/Sub notifications toggle. You can select your topic name, or you can click Create a topic to create one.
  10. Click Save.

When this transfer runs, the BigQuery Data Transfer Service automatically populates the following tables.

Table Name Description
AdAccounts The ad accounts available for a user.
AdInsights Ad insights report for all ad accounts.
AdInsightsActions Ad insights actions report for all ad accounts.


Enter the bq mk command and supply the transfer creation flag --transfer_config:

bq mk \
    --transfer_config \
    --project_id=PROJECT_ID \
    --data_source=DATA_SOURCE \
    --display_name=DISPLAY_NAME \
    --target_dataset=DATASET \


  • PROJECT_ID (optional): your Google Cloud project ID. If --project_id isn't supplied to specify a particular project, the default project is used.
  • DATA_SOURCE: the data source (for example, facebook-ads).
  • DISPLAY_NAME: the display name for the transfer configuration. The transfer name can be any value that lets you identify the transfer if you need to modify it later.
  • DATASET: the target dataset for the transfer configuration.
  • PARAMETERS: the parameters for the created transfer configuration in JSON format. For example: --params='{"param":"param_value"}'. The following are the parameters for a Facebook Ads transfer:
    • connector.authentication.oauth.clientId: The app ID name for the OAuth 2.0 client.
    • connector.authentication.oauth.clientSecret: The app secret for the OAuth 2.0 client.
    • connector.authentication.oauth.refreshToken: The long-lived token ID.

For example, the following command creates a Facebook Ads transfer in the default project with all the required parameters:

    bq mk 
--display_name='My Transfer'
--params='{"connector.authentication.oauth.clientId": "1650000000", "connector.authentication.oauth.clientSecret":"TBA99550", "connector.authentication.oauth.refreshToken":"abcdef"}'


Use the projects.locations.transferConfigs.create method and supply an instance of the TransferConfig resource.

Troubleshoot transfer configuration

If you are having issues setting up a Facebook Ads transfer, check the Required Actions tab on the Facebook App dashboard for any items that require attention.


There is no cost to transfer Facebook Ads data into BigQuery while this feature is in Preview.

What's next