---
title: CSV Uploads Integration Guide | Flyweel Docs
description: Import campaign data to Flyweel via CSV file upload. Complete guide with column specifications, formatting requirements, and troubleshooting for manual data imports.
url: "https://www.flyweel.co/docs/integrations/csv-uploads"
type: static
generatedAt: "2026-09-18T05:57:35.703Z"
---

![Documentation hero background](https://astro-flyweel-docs.vercel.app/vision-hero.webp)
# CSV Uploads

## What is CSV Upload?[Link to this section](#what-is-csv-upload)

CSV Upload allows you to import campaign performance data directly into Flyweel as an alternative to API integrations. Use this feature to consolidate historical data, track custom metrics like Bitcoin costs, and import data from platforms without native API support.

**Unified Analysis**: CSV uploads appear as “CSV Imports” in the platform filter alongside Google Ads and Meta Ads, allowing seamless cross-platform comparison in AdGrid.

## Prerequisites[Link to this section](#prerequisites)

Before uploading a CSV file, ensure you have:

 - A Flyweel account with an active subscription
 - Campaign data formatted according to the column specifications below
 - CSV file saved with UTF-8 encoding (standard for Excel and Google Sheets)
 - File size under 10MB (split larger files by date range)

## How Do I Upload a CSV File to Flyweel?[Link to this section](#how-do-i-upload-a-csv-file-to-flyweel)

Uploading a CSV file takes just a few minutes.

### Navigate to AdGrid

Open the **AdGrid Campaign Manager** in your Flyweel dashboard

### Open Upload Dialog

Click the **Upload CSV** button in the filter sidebar to open the file selector

### Select Your File

Choose your prepared CSV file from your computer. The dialog shows the filename and size for confirmation.

### Upload and Process

Click **Upload** to submit the file. Flyweel validates the data and displays a confirmation with the row count imported.

### View Imported Data

Select **CSV Imports** in the platform filter to view your uploaded campaign data in AdGrid.

## Required CSV Columns[Link to this section](#required-csv-columns)

Your CSV file must include these columns with exact header names (lowercase with underscores):

| Column | Type | Format | Example |
| --- | --- | --- | --- |
| `campaign_id` | String | Unique identifier | `camp_12345` |
| `campaign_name` | String | Display name | `Summer Sale 2024` |
| `date` | Date | YYYY-MM-DD | `2024-07-15` |
| `impressions` | Integer | Whole number | `150000` |
| `clicks` | Integer | Whole number | `3750` |
| `ctr` | Decimal | 0-1 range | `0.025` |
| `cost` | Decimal | Currency amount | `1250.50` |
| `cpm` | Decimal | Cost per mille | `8.33` |

**Column Names Are Case-Sensitive**: Headers must match exactly as shown above. Use lowercase letters with underscores. Spaces or different casing will cause validation errors.

## Optional CSV Columns[Link to this section](#optional-csv-columns)

Enhance your data with these optional columns:

| Column | Type | Format | Example | Use Case |
| --- | --- | --- | --- | --- |
| `conversions` | Integer | Whole number | `125` | Track conversion counts |
| `cost_btc` | Decimal | Bitcoin amount | `0.0042` | Crypto advertising spend |
| `account_name` | String | Account identifier | `Main Account` | Group by data source |
| `currency` | String | ISO 4217 code | `USD`, `EUR`, `GBP` | Multi-currency tracking |

**Organise by Source**: Use the `account_name` column to differentiate data from multiple platforms within a single CSV. For example: “TikTok Campaigns”, “Affiliate Network”, “Legacy Google Ads”.

## Sample CSV File[Link to this section](#sample-csv-file)

Here’s a correctly formatted CSV example:


**

```
campaign_id,campaign_name,date,impressions,clicks,ctr,cost,cpm,conversions,account_namecamp_001,Summer Sale 2024,2024-07-15,150000,3750,0.025,1250.50,8.33,125,Main Accountcamp_001,Summer Sale 2024,2024-07-16,145000,3625,0.025,1200.00,8.28,118,Main Accountcamp_002,Brand Awareness Q3,2024-07-15,200000,2000,0.01,1500.00,7.50,50,Main Accountcamp_003,Crypto Campaign,2024-07-15,80000,1600,0.02,0,0,30,Bitcoin Network
```

## Data Validation[Link to this section](#data-validation)

Flyweel validates your CSV during upload to ensure data quality.

### Validation Rules[Link to this section](#validation-rules)

 - **Required columns**: All eight required columns must be present
 - **Date format**: Must be valid ISO 8601 (YYYY-MM-DD)
 - **Numeric values**: Must be valid numbers without currency symbols or commas
 - **CTR range**: Values should be between 0 and 1 (decimal, not percentage)
 - **No empty rows**: All rows must contain data for required columns

### Common Validation Errors[Link to this section](#common-validation-errors)

| Error Message | Cause | Solution |
| --- | --- | --- |
| Missing required column | Column header not found or misspelled | Check spelling and case (must be lowercase) |
| Invalid date format | Date not in YYYY-MM-DD format | Reformat dates in spreadsheet |
| Invalid number in cost | Text or symbols in numeric field | Remove currency symbols, commas, and spaces |
| CTR out of range | CTR entered as percentage (e.g., 2.5) | Convert to decimal (2.5% = 0.025) |
| File too large | CSV exceeds 10MB limit | Split file by date range |

## Updating Existing Data[Link to this section](#updating-existing-data)

To update previously uploaded data:

 1. Create a CSV with the same `campaign_id` and `date` combinations
 1. Include all required columns with updated values
 1. Upload the file—existing records are automatically updated

**Partial Updates**: You can update specific date ranges by including only those dates. Records not in the new file remain unchanged in your dashboard.

## Best Practices[Link to this section](#best-practices)

### Data Preparation[Link to this section](#data-preparation)

 - **Consistent IDs**: Use the same campaign_id format across all uploads for the same campaign
 - **Complete rows**: Include all required columns for every row
 - **UTF-8 encoding**: Save as UTF-8 to preserve special characters (default in modern spreadsheets)
 - **No BOM**: Ensure your file does not include a Byte Order Mark if exporting from older systems

### Large Datasets[Link to this section](#large-datasets)

For files with more than 50,000 rows:

 1. Split into multiple files organised by date range (e.g., monthly files)
 1. Upload sequentially, waiting for each to complete
 1. Verify row counts match your source data in the upload confirmation
 1. Use the account_name column to keep data organised

### Multi-Source Data[Link to this section](#multi-source-data)

When consolidating data from multiple platforms:

 - Use unique campaign_id prefixes (e.g., `tiktok_camp_001`, `affiliate_camp_001`)
 - Set account_name to identify the source platform
 - Maintain consistent naming across uploads for accurate trend analysis

## Viewing Uploaded Data[Link to this section](#viewing-uploaded-data)

After uploading:

 1. Navigate to **AdGrid Campaign Manager**
 1. Open the **platform filter** dropdown
 1. Select **CSV Imports** to view only uploaded data
 1. Or combine with other platforms for cross-channel analysis

Your CSV data integrates fully with Flyweel’s features:

 - **Filter and search** by campaign name, date range, or account
 - **Generate reports** including CSV data alongside API-synced campaigns
 - **AI analysis** treats CSV data identically to connected platforms

## Troubleshooting[Link to this section](#troubleshooting)

### Upload Failures[Link to this section](#upload-failures)

If your upload fails:

 1. Check file size is under 10MB
 1. Verify the file is saved as CSV (not .xlsx or .numbers)
 1. Open the file in a text editor to confirm comma separation
 1. Check for hidden characters or BOM markers from older software
 1. Ensure all required columns are present with correct names

### Data Not Appearing[Link to this section](#data-not-appearing)

If uploaded data does not appear in AdGrid:

 1. Wait 1-2 minutes for processing to complete
 1. Refresh the page
 1. Verify the platform filter includes “CSV Imports”
 1. Check the date range in your filter includes your uploaded dates
 1. Review the upload confirmation for any warnings

### Incorrect Values[Link to this section](#incorrect-values)

If values appear incorrect in the dashboard:

 1. Verify decimal formats use period (.) not comma (,) as separator
 1. Check CTR is decimal (0.025) not percentage (2.5%)
 1. Ensure date format is YYYY-MM-DD
 1. Review the currency column if costs seem wrong
 1. Check for leading/trailing spaces in campaign_id

### Duplicate Data[Link to this section](#duplicate-data)

If you see duplicate campaigns:

 1. Verify campaign_id values are consistent across uploads
 1. Check for invisible character differences (copy-paste from different sources)
 1. Review account_name values for unintended variations

## Frequently Asked Questions[Link to this section](#frequently-asked-questions)

### What data can I import via CSV to Flyweel?[Link to this section](#what-data-can-i-import-via-csv-to-flyweel)

You can import campaign performance data including campaign ID, campaign name, date, impressions, clicks, CTR, cost, and CPM. Optional fields include conversions, Bitcoin costs (cost_btc), account name for grouping, and currency code.

### What is the maximum file size for CSV uploads?[Link to this section](#what-is-the-maximum-file-size-for-csv-uploads)

Flyweel supports CSV files up to 10MB per upload. For larger datasets, split your data into multiple files organised by date range and upload them sequentially.

### Can I use CSV uploads alongside Google Ads and Meta Ads?[Link to this section](#can-i-use-csv-uploads-alongside-google-ads-and-meta-ads)

Yes. CSV uploads work seamlessly alongside API integrations. Uploaded data appears as “CSV Imports” in the platform filter alongside Google Ads and Meta Ads for unified analysis.

### How do I format the CTR column correctly?[Link to this section](#how-do-i-format-the-ctr-column-correctly)

CTR must be a decimal between 0 and 1, not a percentage. Convert percentages by dividing by 100. For example: 2.5% becomes 0.025, 15% becomes 0.15.

### Can I track Bitcoin advertising costs?[Link to this section](#can-i-track-bitcoin-advertising-costs)

Yes. The optional cost_btc column allows you to track campaign costs in Bitcoin alongside fiat currencies. This is useful for crypto-native ad networks and affiliate programs.

### How do I update previously uploaded data?[Link to this section](#how-do-i-update-previously-uploaded-data)

Upload a new CSV file with the same campaign_id and date combinations. Flyweel automatically updates existing records with the new values.

### Can I import data from multiple platforms in one CSV?[Link to this section](#can-i-import-data-from-multiple-platforms-in-one-csv)

Yes. Use the account_name column to differentiate data sources. Set values like “TikTok Campaigns” or “Affiliate Network” to group campaigns by their source.

### How quickly does CSV data appear in Flyweel?[Link to this section](#how-quickly-does-csv-data-appear-in-flyweel)

CSV data typically processes within 1-2 minutes. Once processed, data appears immediately in AdGrid under the “CSV Imports” filter.

### What happens if my CSV has formatting errors?[Link to this section](#what-happens-if-my-csv-has-formatting-errors)

Flyweel validates your CSV during upload and displays specific error messages. Fix the identified issues in your spreadsheet and re-upload the corrected file.

### Can I delete uploaded CSV data?[Link to this section](#can-i-delete-uploaded-csv-data)

Yes. Navigate to Settings > Data Management, locate your CSV import in the history, and click Delete. This removes all data from that specific upload.

## Next Steps[Link to this section](#next-steps)

Once you have uploaded your CSV data:

 1. **Explore AdGrid**: Use the [AdGrid Campaign Manager](/docs/features/adgrid-campaign-manager) to analyze CSV data alongside API-connected campaigns
 1. **Connect APIs**: Add [Google Ads](/docs/integrations/google-ads) or [Meta Ads](/docs/integrations/meta-ads) for real-time data alongside historical CSV imports
 1. **Generate Reports**: Use [Reports & Analytics](/docs/features/reports-analytics) to include CSV data in automated reports

---

**Need Help?** Contact our support team at [team@flyweel.co](mailto:team@flyweel.co) for assistance with CSV uploads.

### Ready to get started?

Start optimizing your ad spend today with Flyweel.
  [Start Free](https://signup.flyweel.co/?variant=control)