> 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/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Verify your CSV URL before creating a flow</strong></td><td>Test the URL in an incognito browser window to confirm it's publicly accessible and returns the expected CSV data. This saves time debugging connection issues later.</td></tr><tr><td><strong>Use shareable links for Google Drive files</strong></td><td>Right-click the file → Share → "Anyone with the link" → copy the shareable link. Avoid using the regular Google Drive URL—it won't work with Coupler.io.</td></tr><tr><td><strong>Include authentication headers for API-based CSV exports</strong></td><td>If your CSV source requires authentication (e.g., API key, bearer token), add it to the "HTTP request headers" field. Format: `Authorization: Bearer YOUR_TOKEN` or `X-API-Key: YOUR_KEY`.</td></tr><tr><td><strong>Start with a manual run before scheduling</strong></td><td>Always test your data flow with a manual run to confirm it imports correctly. Only then set up a schedule. A failed manual run prevents scheduling.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Match your schedule to your CSV update frequency</strong></td><td>If your CSV source updates daily, schedule refreshes daily. If it updates weekly, refresh weekly. Refreshing more often than your source updates wastes quota.</td></tr><tr><td><strong>Use append mode for time-series data</strong></td><td>If you're importing daily or weekly snapshots, use Append mode to keep historical records. This is ideal for tracking metrics over time (revenue, user counts, etc.).</td></tr><tr><td><strong>Use replace mode for current-state data</strong></td><td>If your CSV always contains the latest snapshot and you only care about the current state, use Replace mode to overwrite old data.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Import only the columns you need</strong></td><td>Specify a comma-separated list of columns in the "Columns" field. This reduces processing time and keeps your destination cleaner, especially for large CSVs.</td></tr><tr><td><strong>Split very large CSVs across multiple flows</strong></td><td>If your CSV has millions of rows, consider importing it to BigQuery instead of Google Sheets (which has a 10 million cell limit). Or split the source CSV by time period or category and create separate flows.</td></tr><tr><td><strong>Use query parameters or POST bodies to filter at the source</strong></td><td>If your CSV source supports filtering (e.g., by date range, category, API parameters), use the "URL query parameters" or "Request body" fields to pull only the data you need.</td></tr></tbody></table>

## Common pitfalls

{% columns %}
{% column %}
**Do**

* Test your CSV URL in an incognito window to verify it's public
* Use direct CSV file links, not webpage URLs
* Include API keys or bearer tokens in the HTTP headers field if required
* Start with a manual run before setting up schedules
* Use the Columns field to import only what you need
  {% endcolumn %}

{% column %}
**Don't**

* Share regular Google Drive URLs—always use the shareable link
* Assume a CSV is public without testing it in incognito mode
* Leave sensitive API keys in plain text if sharing your flow setup
* Schedule imports more frequently than your source updates
* Attempt to import multi-million-row CSVs to Google Sheets without splitting them
  {% endcolumn %}
  {% endcolumns %}

{% hint style="danger" %}
**CSV parsing errors are often caused by unescaped quotes in the source file.** If you see "Invalid Opening Quote" errors, download the CSV locally and inspect it in a text editor. Properly formatted CSVs escape internal quotes as `\"` or use consistent delimiters. If the source file is malformed, ask your CSV provider to export with proper escaping.
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.