Meta ads performance tracker AI agent

What This Agent Does

This workflow automates the process of extracting Facebook Ads performance data and logging it to Google Sheets, giving you a complete view of your advertising metrics without manual data entry. It runs on two parallel tracks: a daily automated export that captures fresh insights every morning at 6:00 AM, and a manual backfill option that lets you populate historical data whenever needed.

Key benefits include:

• Save 30+ minutes daily by eliminating manual report downloads and data entry
• Maintain consistent tracking with automated daily snapshots of your ad performance
• Build historical datasets effortlessly using the backfill feature for trend analysis
• Centralize your metrics in Google Sheets where your team can access, analyze, and visualize data

This workflow is perfect for digital marketers managing Facebook ad campaigns, agencies reporting to clients, e-commerce businesses tracking ROAS, and any organization that needs reliable, automated ad performance tracking.

Required Integrations

Facebook Ads Integration

You need this integration to pull advertising insights, metrics, and performance data directly from your Facebook Ads account. This connection enables TaskAGI to access campaign statistics, spend data, impressions, clicks, conversions, and other key performance indicators.

Setup steps:

1. Navigate to Integrations in your TaskAGI dashboard
2. Search for "Facebook Ads" and click Connect
3. You'll need a Facebook Ads Access Token with the following permissions:
   • ads_read - to read ad account data
   • ads_management - to access insights
4. To obtain your access token:
   • Go to Facebook Business Manager
   • Navigate to Business Settings → Users → System Users
   • Create a new system user or select an existing one
   • Click Generate New Token
   • Select your ad account and grant the necessary permissions
   • Copy the generated token (store it securely - you won't see it again!)
5. Paste the access token into TaskAGI's Facebook Ads integration configuration
6. Enter your Ad Account ID (format: act_123456789)
7. Click Test Connection to verify everything works
8. Save the integration

Pro tip: Use a system user rather than your personal account for better security and stability.

Google Sheets Integration

This integration allows TaskAGI to write data directly to your spreadsheet, creating an automated data pipeline that updates your reports without any manual intervention.

Setup steps:

1. Go to Integrations in TaskAGI and find "Google Sheets"
2. Click Connect with Google
3. Select the Google account that has access to your target spreadsheet
4. Grant TaskAGI the following permissions:
   • View and manage spreadsheets in Google Drive
   • Create, edit, and delete spreadsheets
5. Complete the OAuth authorization flow
6. Once connected, you'll see a green checkmark confirming the integration is active

Important: The Google account you connect must have edit access to any spreadsheet you want to write data to. If you're using a shared spreadsheet, make sure the connected account is listed as an editor.

Configuration Steps

Step 1: Set Up Your Google Sheet

Before configuring the workflow, prepare your destination spreadsheet:

1. Create a new Google Sheet or open an existing one
2. Add column headers in the first row (see the "Help & Column Headers" note in the workflow for recommended headers like: Date, Campaign Name, Impressions, Clicks, Spend, CPC, CTR, Conversions, Cost Per Conversion)
3. Copy the full URL of your Google Sheet
4. Keep this URL handy - you'll need it for configuration

Step 2: Configure Daily Export Flow

Daily Schedule Node (06:00):

• This trigger is pre-configured to run at 6:00 AM in your account's timezone
• To change the schedule, click the node and modify the time using the time picker
• Consider your reporting needs: early morning captures complete previous-day data

Daily Config Node:

• This function node prepares parameters for your daily data fetch
• Configure these key parameters:
  • date_preset: Set to "yesterday" to fetch the previous day's complete data
  • level: Choose "campaign", "adset", or "ad" depending on your reporting granularity
  • fields: Specify metrics like ["impressions", "clicks", "spend", "conversions", "cpc", "ctr"]
  • breakdowns: Optional - add dimensions like ["age", "gender", "placement"] for deeper analysis

Example configuration:

{
  date_preset: "yesterday",
  level: "campaign",
  fields: ["campaign_name", "impressions", "clicks", "spend", "conversions", "cpc", "ctr", "cpm"],
  time_increment: 1
}

Fetch Meta Insights (Daily) Node:

• This node receives configuration from the Daily Config node
• Select your connected Facebook Ads integration from the dropdown
• The ad_account_id should reference your configured integration
• Leave insights_config mapped to [[nodes.3334.result]] to use the config from the previous node

Transform Data for Sheets Node:

• This function formats the raw Facebook data into rows suitable for Google Sheets
• The transformation typically:
  • Flattens nested JSON structures
  • Formats dates consistently
  • Converts numeric values to proper formats
  • Orders fields to match your sheet headers
• Customize the transformation logic if you need specific formatting or calculated fields

Append to Google Sheet Node:

• Click the node and paste your Google Sheet URL in the sheet_url field
• Alternatively, reference it from the Transform node: [[nodes.3336.sheetUrl]]
• Set sheet_name to the specific tab name (e.g., "Daily Data")
• The values field should map to [[nodes.3336.result]] to receive transformed data
• Enable include_headers only on first run, then disable to avoid duplicate headers

Step 3: Configure Backfill Flow

The backfill flow mirrors the daily flow but runs manually when you need historical data.

Manual Trigger Node:

• This requires no configuration - simply click "Run" when you need to backfill data
• Use this when setting up the workflow initially or filling data gaps

Backfill Config Node:

• Configure date ranges for historical data:
  • date_preset: Use "custom" for specific date ranges
  • time_range: Specify {"since": "2024-01-01", "until": "2024-01-31"} format
  • Keep other parameters consistent with your daily config for data consistency

Example backfill configuration:

{
  date_preset: "custom",
  time_range: {
    since: "2024-01-01",
    until: "2024-01-31"
  },
  level: "campaign",
  fields: ["campaign_name", "impressions", "clicks", "spend", "conversions", "cpc", "ctr", "cpm"],
  time_increment: 1
}

Remaining Backfill Nodes:

• Configure identically to the daily flow nodes
• Ensure the backfill append node points to the same Google Sheet (or a separate "Historical Data" tab if preferred)

Testing Your Agent

Initial Test Run

1. Test the backfill flow first (it's easier to verify manually):

   • Click the "Manual Trigger" node
   • Click Run Node in the right panel
   • Watch the execution flow through each node

2. Verify each step:

   • Backfill Config: Check that the output shows your expected date range and parameters
   • Fetch Meta Insights: Confirm that insights data is returned (look for arrays of campaign data)
   • Transform Data: Verify the data is formatted as rows matching your sheet structure
   • Append to Google Sheet: Check for a success message and no errors

3. Check your Google Sheet:

   • Open your spreadsheet
   • Verify that new rows appeared with the correct data
   • Confirm dates, metrics, and formatting look correct
   • Ensure no duplicate headers were added

Testing Daily Automation

Since the daily trigger runs at 6:00 AM, you have two testing options:

Option 1 - Wait for scheduled run:

• Let the workflow run at its scheduled time
• Check your sheet the next morning
• Review the execution log in TaskAGI under Workflow Runs

Option 2 - Manual test (recommended):

• Click the "Daily Schedule" trigger node
• Click Run Node to simulate the scheduled trigger
• Follow the same verification steps as the backfill test
• This confirms everything works before waiting for the actual schedule

Success Indicators

✅ Execution completes without red error indicators on any node ✅ Data appears in your Google Sheet within 30 seconds of execution ✅ Metrics are accurate when compared to Facebook Ads Manager ✅ No duplicate rows are created on subsequent runs ✅ Date formatting is consistent and readable

Troubleshooting

"Failed to fetch insights" Error

Cause: Usually related to Facebook Ads API permissions or invalid ad account ID.

Solutions:

• Verify your ad account ID is in the correct format: act_123456789
• Check that your access token hasn't expired (they typically last 60 days)
• Ensure the connected Facebook user has access to the specified ad account
• Regenerate your access token with proper permissions if needed

"Permission denied" on Google Sheets

Cause: The connected Google account lacks edit access to the spreadsheet.

Solutions:

• Open your Google Sheet and check the sharing settings
• Add the connected Google account as an Editor
• If using a service account, share the sheet with the service account email
• Reconnect the Google Sheets integration if permissions were recently changed

Duplicate Headers Appearing

Cause: The include_headers option is enabled on repeated runs.

Solutions:

• Edit the "Append to Google Sheet" nodes
• Set include_headers to false
• Manually delete duplicate header rows from your sheet
• Headers should only be included on the very first run

Missing or Incomplete Data

Cause: Date ranges might not be fully processed by Facebook, or fields aren't available for your account.

Solutions:

• For daily runs, ensure you're fetching "yesterday" data (today's data is incomplete)
• Check that all requested fields are available for your ad account level
• Some metrics require specific campaign objectives or conversion tracking
• Review Facebook's Insights API documentation for field availability

Transform Function Errors

Cause: The data structure from Facebook doesn't match expected format.

Solutions:

• Check the raw output from "Fetch Meta Insights" node
• Adjust the transform function to handle the actual data structure
• Add error handling for missing or null values
• Test with a small date range first to debug transformation logic

Workflow Doesn't Run on Schedule

Cause: Workflow might be paused, or schedule configuration is incorrect.

Solutions:

• Check that the workflow is Active (toggle in top-right corner)
• Verify the schedule timezone matches your expectations
• Review the execution history to see if runs are failing silently
• Ensure your TaskAGI account has sufficient execution credits

Next Steps

After Successful Setup

🎉 Congratulations! Your automated Facebook Ads reporting is now live. Here's what to do next:

1. Monitor for a week - Check your sheet daily to ensure consistent data flow
2. Set up visualizations - Create charts and pivot tables in Google Sheets for quick insights
3. Share with stakeholders - Give team members view or edit access to the sheet
4. Document your metrics - Add a "README" tab explaining what each column means

Optimization Suggestions

Expand your metrics:

• Add more fields like "frequency", "reach", "unique_clicks", or "roas"
• Include breakdowns by age, gender, or placement for deeper analysis
• Track link clicks, landing page views, or custom conversion events

Create multiple sheets:

• Set up separate tabs for campaign, ad set, and ad-level data
• Create a summary tab with formulas pulling key metrics
• Build a dashboard tab with charts and conditional formatting

Add alerting:

• Use Google Sheets' built-in notification rules for anomalies
• Set up conditional formatting to highlight performance issues
• Create a separate workflow that sends Slack/email alerts for specific thresholds

Enhance data quality:

• Add data validation in your transform function
• Include calculated fields like ROAS, profit margins, or efficiency scores
• Implement deduplication logic if running backfills multiple times

Advanced Usage Tips

Historical trend analysis:

• Run the backfill for the past 90 days to establish baseline performance
• Use time_increment: 1 for daily granularity or time_increment: 7 for weekly rollups
• Create year-over-year comparison sheets for seasonal businesses

Multi-account management:

• Duplicate the workflow for each ad account you manage
• Modify each to write to different sheet tabs or separate spreadsheets
• Use consistent naming conventions for easy identification

Integration with other tools:

• Export your Google Sheet data to Data Studio (Looker Studio) for advanced visualization
• Connect to BigQuery for data warehousing and complex analysis
• Use the sheet as a data source for your BI tools like Tableau or Power BI

Performance optimization:

• If dealing with large accounts, consider filtering by specific campaigns
• Use pagination parameters for accounts with 100+ campaigns
• Schedule backfills during off-peak hours to avoid rate limiting

Your automated Facebook Ads reporting system is now a powerful asset that will save you time and provide consistent, reliable data for decision-making. As you become comfortable with the workflow, explore TaskAGI's other nodes to add even more automation to your marketing operations! 🚀