> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/files-and-tables/csv.md).

# CSV

Import CSV files from Google Drive, public servers, or APIs into Google Sheets, BigQuery, and AI tools via Coupler.io.

CSV (Comma-Separated Values) is a simple, universal file format for storing tabular data. Coupler.io lets you import CSV files from anywhere online—whether hosted on Google Drive, a public server, or an API endpoint—directly into Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude, ChatGPT, and Gemini.

## Why connect CSV to Coupler.io?

* **Pull data from any public CSV source** — no matter where it's hosted
* **Automate recurring imports** — refresh your spreadsheet on a schedule without manual downloads
* **Preserve data formatting** — import with control over columns, headers, and row skipping
* **Route to any destination** — send CSV data to Google Sheets, Excel, BigQuery, Looker Studio, or AI platforms

## Prerequisites

* A publicly accessible CSV file (or a shareable link if using Google Drive)
* The direct link to the CSV file
* Depending on your CSV source, you may need HTTP headers or authentication details (e.g., API keys or bearer tokens)

## Quick start

{% hint style="success" %}
The simplest setup: grab a public CSV URL and point Coupler.io to it. No API keys required for basic imports.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow.** Open Coupler.io and start a new data flow. Select CSV as your data source.
{% endstep %}

{% step %}
**Paste your CSV URL.** Enter the direct link to your CSV file (e.g., `https://example.com/data.csv` or a Google Drive shareable link). The URL must point directly to the CSV file, not a webpage.
{% endstep %}

{% step %}
**Choose HTTP method.** Select GET (most common) or POST, PUT, PATCH, DELETE if your CSV source requires a specific method. Check your data source's API documentation if unsure.
{% endstep %}

{% step %}
**Add headers or authentication (optional).** If your CSV requires API authentication, add HTTP request headers (e.g., `Authorization: Bearer YOUR_TOKEN`) in the HTTP request headers field.
{% endstep %}

{% step %}
**Select columns (optional).** By default, Coupler.io imports all columns. To import specific columns only, list them comma-separated (e.g., `id,name,date,amount`).
{% endstep %}

{% step %}
**Skip header rows (optional).** If your CSV has multiple header rows or metadata at the top, specify the number of rows to skip.
{% endstep %}

{% step %}
**Choose your destination.** Select where to send the data: Google Sheets, Excel, BigQuery, Looker Studio, or an AI platform (Claude, ChatGPT, Cursor, Gemini, Perplexity, OpenClaw).
{% endstep %}

{% step %}
**Run the data flow.** Click "Run" to test the import. Wait for it to complete successfully before any further configuration.
{% endstep %}
{% endstepper %}

## Common CSV sources

| Source Type   | Example                                                | Notes                                                   |
| ------------- | ------------------------------------------------------ | ------------------------------------------------------- |
| Google Drive  | Shareable link to CSV file                             | Must be publicly shared                                 |
| Public URLs   | `https://example.com/data.csv`                         | Direct link to CSV file                                 |
| API endpoints | CSV export endpoints (e.g., Clockify, analytics tools) | May require POST method and authentication headers      |
| FTP servers   | FTP-hosted CSV files                                   | Limited support; include credentials in URL if required |

## CSV data overview

CSV is a flexible, format-agnostic source. The data you import depends entirely on the structure of your CSV file—there are no predefined entities or reports.

## What you can import

Coupler.io treats your CSV as a flat table. Whatever columns and rows are in your CSV file will be imported as-is:

* **Columns** — become the headers in your destination (or you can select specific columns)
* **Rows** — all data rows are imported (or you can skip header rows if needed)
* **Data types** — imported as text by default; formatting and type conversions happen in your destination

## Metrics and dimensions

Since CSV is format-agnostic, there are no predefined metrics or dimensions. Your CSV might contain:

* **Time-series data** — dates, timestamps, daily/weekly/monthly aggregates
* **Financial data** — revenue, costs, margins, percentages
* **Operational data** — IDs, names, categories, statuses, counts
* **Performance data** — conversion rates, click-through rates, engagement metrics

## Common use cases by role

{% tabs %}
{% tab title="Marketers" %}
Import campaign performance data, ad spend reports, and lead lists from marketing tools that export to CSV. Use Coupler.io to refresh your campaign dashboard in Google Sheets daily, then visualize with Looker Studio.
{% endtab %}

{% tab title="Finance teams" %}
Automated CSV imports work great for pulling exported transaction logs, budget snapshots, and reconciliation data from accounting systems. Append data from multiple periods or accounts, then aggregate in your spreadsheet for monthly close reporting.
{% endtab %}

{% tab title="Operations & HR" %}
Pull time tracking data (e.g., Clockify), attendance records, or project schedules exported as CSV. Schedule daily refreshes to keep your team's capacity planning and billing sheets current.
{% endtab %}

{% tab title="Sales ops" %}
Import pipeline snapshots, deal stage reports, and activity logs exported from CRM systems. Use Coupler.io to consolidate CSVs from multiple regions or time periods into a single source of truth.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Google Drive CSVs** — Use the "Get shareable link" option and ensure the file is publicly accessible. The link format is typically `https://drive.google.com/uc?export=download&id=FILE_ID`
* **API-based CSV exports** — Some tools (e.g., Clockify, analytics platforms) offer CSV export via POST requests. You may need to include authentication headers or request parameters.
* **Large files** — Google Sheets has a 10 million cell limit; if your CSV exceeds this, consider splitting into multiple flows or using BigQuery as a destination
* **CSV formatting** — Ensure proper quote escaping and encoding (UTF-8 recommended); files with unescaped quotes may cause parsing errors
* **Scheduled refreshes** — CSV imports are ideal for daily or weekly schedules; very frequent refreshes (every minute) may not be necessary if the source updates infrequently

## CSV common issues

### Connection issues

<details>

<summary>"Can't access your CSV file" error</summary>

This usually means your URL is not publicly accessible or not formatted correctly.

**Fix:**

* If using Google Drive, right-click the file → "Share" → "Change to "Anyone with the link" → "Viewer" → copy the shareable link
* Verify the URL points directly to the CSV file, not a landing page or preview page
* Test the URL in an incognito browser window to confirm it's public
* For API-based CSV exports, check that any required authentication headers (API keys, bearer tokens) are included in the "HTTP request headers" field

</details>

<details>

<summary>HTTP 405 "Method Not Allowed" error</summary>

Your CSV source requires a specific HTTP method (POST, PUT, etc.), but you selected GET.

**Fix:**

* Check your CSV source's API documentation to see which method is required
* Change the HTTP method in Coupler.io to match (e.g., POST, PATCH)
* Some sources like Clockify require POST for CSV exports

</details>

<details>

<summary>"Invalid Opening Quote" or CSV parse error</summary>

Your CSV contains unescaped quotation marks or special characters that confuse the parser.

**Fix:**

* Verify the CSV is properly formatted with escaped quotes (e.g., `"text with \"quotes\" inside"`)
* Download the CSV locally and open it in a text editor to inspect for formatting issues
* If the quote issue is in your source system, ask the provider to export with proper escaping
* Try using the "Ignore quotes" option in advanced settings if your CSV doesn't rely on quotes for field delimiting

</details>

<details>

<summary>Request times out or fails with no response</summary>

The CSV URL is slow to respond or unreachable from Coupler.io's servers.

**Fix:**

* Verify the URL is correct and responsive by testing it in your browser
* Check if your CSV source has rate limits or requires specific headers (User-Agent, etc.)
* If using an API endpoint, ensure any authentication tokens are current and not expired
* Try again after a few minutes; temporary network issues can cause timeouts

</details>

### Missing data

<details>

<summary>No data imported, but no error shown</summary>

The CSV was found and parsed, but it contained no data rows (only headers or empty file).

**Fix:**

* Verify the CSV file actually contains data by downloading and opening it locally
* Check if you're skipping too many rows with the "Skip rows" setting
* If the CSV is generated dynamically (e.g., API export), verify it returned data for the date range or filters you applied

</details>

<details>

<summary>Only partial columns imported</summary>

You may have specified a limited column list in the "Columns" field, or the CSV source only provided some columns.

**Fix:**

* Check the "Columns" field—if you want all columns, leave it empty
* Verify your CSV source returns all expected columns by testing the URL directly
* If using an API, check that you're not applying filters that exclude columns

</details>

<details>

<summary>Timestamps or dates are missing or incorrect</summary>

Date formatting issues or timezone mismatches can cause dates to appear wrong.

**Fix:**

* Verify dates in the source CSV are in a standard format (ISO 8601: YYYY-MM-DD recommended)
* Check your destination (Google Sheets, etc.) date formatting settings
* If your CSV source allows date range filters, ensure the date range includes the data you expect

</details>

### Permission errors

<details>

<summary>Google Drive file not accessible (403 Forbidden)</summary>

The file is shared with you personally, but not publicly shared.

**Fix:**

* Open the file in Google Drive, click "Share" at the top right
* Change the sharing setting from "Restricted" or "Shared with specific people" to "Anyone with the link"
* Set the role to "Viewer"
* Copy the shareable link and use it in Coupler.io

</details>

<details>

<summary>API key or bearer token rejected</summary>

Your authentication header is missing, invalid, or expired.

**Fix:**

* Verify the API key/token format matches your source's requirements (e.g., `Authorization: Bearer YOUR_TOKEN` or `X-API-Key: YOUR_KEY`)
* Check that your token hasn't expired; regenerate it if needed
* Ensure there are no extra spaces or typos in the header value
* Test the URL with the same header in Postman or curl to confirm it works

</details>

### Data discrepancies

<details>

<summary>CSV imported with extra blank rows at the end</summary>

Some CSV files have trailing empty lines that get imported as rows.

**Fix:**

* This is expected behavior; blank rows are preserved as-is from the source
* Clean them up in your destination using filters or formulas, or download the CSV and remove them before uploading
* The "Skip rows" setting only skips rows from the *top*; it doesn't remove trailing blank rows

</details>

<details>

<summary>Data appears truncated or wrapped oddly in the destination</summary>

Large text fields or special characters may display unexpectedly in your destination.

**Fix:**

* Adjust column width in your destination (Google Sheets, Excel, etc.)
* Check for hidden characters or encoding issues in the source CSV
* If using BigQuery or another data warehouse, verify the schema allows the data type and length

</details>

### Rate limits

<details>

<summary>"Rate limit exceeded" error on repeated imports</summary>

Your CSV source is throttling requests. This is common with API-based CSV exports.

**Fix:**

* Space out your scheduled refreshes; avoid running the same import multiple times per hour
* Check your CSV source's rate limit policy (e.g., Clockify, analytics APIs often allow 1-10 requests per minute)
* If scheduling, use longer intervals (daily vs. hourly) or distribute multiple flows across different times
* Contact your CSV source's support if you need higher rate limits

</details>

## CSV FAQ

<details>

<summary>Can I import CSV files from any website?</summary>

Yes, as long as the CSV file is publicly accessible via a direct URL. You can import from public servers, Google Drive (with a shareable link), API endpoints, or anywhere else online. The URL must point directly to the CSV file, not a webpage or landing page.

</details>

<details>

<summary>How do I import a CSV from Google Drive?</summary>

Right-click the CSV file in Google Drive, select "Share," change the setting to "Anyone with the link," and set the role to "Viewer." Copy the shareable link and paste it into Coupler.io. Do NOT use the regular Google Drive URL—it won't work with Coupler.io.

</details>

<details>

<summary>Can I filter my CSV before importing (e.g., by date range)?</summary>

It depends on your CSV source. If your source is an API endpoint that supports query parameters or POST filters (e.g., Clockify, analytics platforms), use the "URL query parameters" or "Request body" fields to specify filters. If your CSV is a static file, you'll need to clean it up after import using formulas in your destination.

</details>

<details>

<summary>What HTTP method should I use?</summary>

Most public CSV files use GET. However, some sources (like Clockify's CSV export API) require POST. Check your CSV source's documentation. If unsure, start with GET; if it fails with a "405 Method Not Allowed" error, switch to POST.

</details>

<details>

<summary>Do I need to provide authentication to import a CSV?</summary>

Only if your CSV source requires it. Public CSVs don't need authentication. If your source is an API endpoint or protected file, add authentication headers (e.g., `Authorization: Bearer YOUR_TOKEN`) in the "HTTP request headers" field.

</details>

<details>

<summary>Can I append multiple CSV imports into one sheet?</summary>

Yes. Create separate data flows for each CSV source, and use Append mode on each. Coupler.io will add new rows below existing data each time it runs. This is great for consolidating time-series data or reports from multiple accounts.

</details>

<details>

<summary>What's the difference between Replace and Append mode?</summary>

Replace mode overwrites all data each refresh (good for current-state snapshots). Append mode adds new rows below existing data (good for historical tracking). You can choose the mode when setting up your destination in the data flow.

</details>

<details>

<summary>How often can I refresh my CSV import?</summary>

You can schedule refreshes as frequently as every 15 minutes (depending on your plan). However, refresh only as often as your CSV source updates. Refreshing more frequently than your source changes is wasteful and may hit rate limits.

</details>

<details>

<summary>Can I transform or reformat my CSV data during import?</summary>

Coupler.io imports CSV data as-is. To transform or reformat, use Google Sheets formulas, BigQuery queries, or another transformation tool. You can also use Coupler.io's Join, Append, and Aggregate transformations if combining multiple CSV sources or entities.

</details>

<details>

<summary>What should I do if I get a "CSV parse error: Invalid Opening Quote" message?</summary>

This error usually means the CSV has unescaped quotes or special characters. Download the CSV file locally, open it in a text editor, and check the formatting. Properly formatted CSVs use consistent delimiters and escape internal quotes. If the source file is malformed, contact your CSV provider and ask them to export with proper escaping. Alternatively, try the "Ignore quotes" option in advanced settings.

</details>

<details>

<summary>Can I import a CSV from an FTP server?</summary>

Support for FTP is limited. If your FTP server has a public URL or allows HTTP access, use that URL in Coupler.io. If credentials are required, include them in the URL (e.g., `ftp://username:password@server.com/file.csv`) or as headers.

</details>

<details>

<summary>Why is my import showing fewer rows than expected?</summary>

Check the "Skip rows" setting—if set too high, you may skip data. Also verify that your CSV source returned all expected data (test the URL directly). If using filters, confirm they're not excluding rows. Finally, ensure the CSV isn't too large; Google Sheets has a 10 million cell limit.

</details>

<details>

<summary>Can I send my CSV data to BigQuery or Data Studio instead of Google Sheets?</summary>

Yes. When setting up your data flow, choose BigQuery, Data Studio, or any other supported destination. CSV imports work with Google Sheets, Excel, BigQuery, Data Studio, and AI platforms (Claude, ChatGPT, Gemini, etc.). BigQuery is great for very large CSVs that exceed Google Sheets' row limits.

</details>

{% hint style="info" %}
For more detailed troubleshooting, see [Common Issues](#csv-common-issues). For optimization tips, check out [Best Practices](https://docs.coupler.io/sources/category/files-and-tables/csv/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/files-and-tables/csv.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
