# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Test with Postman first</strong></td><td>Before creating a data flow, test your API endpoint in Postman or your browser. Verify the URL works, authentication is correct, and the response format is what you expect. This saves troubleshooting time in Coupler.io.</td></tr><tr><td><strong>Use path to extract nested data</strong></td><td>If your API response has nested objects, always <a href="best-practices/how-to-define-the-path-for-selecting-json-objects">use the **Path** field to target the specific array or object you need</a> (e.g., `data.results` or `payload.users`). This keeps your import clean and avoids flattening unrelated data.</td></tr><tr><td><strong>Select only columns you need</strong></td><td>In the **Columns** field, list only the columns you'll actually use. This reduces data transfer time, keeps your destination sheet or table cleaner, and is especially helpful for large APIs with many fields.</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>Space out scheduled runs for rate-limited APIs</strong></td><td>If your API has rate limits, schedule data flows at intervals that stay well within the limit. For example, if the API allows 1000 requests/hour, run your flow every 30+ seconds to be safe. Stagger multiple flows hitting the same API.</td></tr><tr><td><strong>Run a successful manual test before scheduling</strong></td><td>Always execute a manual run and confirm the data arrives correctly before setting up a schedule. This ensures your configuration is correct and your destination is properly connected.</td></tr><tr><td><strong>Configure retries for unreliable APIs</strong></td><td>If your API occasionally fails or times out, set **Retries Count** to 3–5 and **Retries Delay** to 2000–5000 ms. This helps your data flow recover from temporary network or API glitches without manual intervention.</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>Use query parameters to filter at the source</strong></td><td>If your API supports filtering (e.g., `?status=active&#x26;created_after=2024-01-01`), add these in **URL query parameters**. Filtering at the source reduces data transfer and speeds up your flow.</td></tr><tr><td><strong>Handle pagination in separate flows</strong></td><td>If your API returns paginated results, create one data flow per page (e.g., `?limit=500&#x26;offset=0`, `?limit=500&#x26;offset=500`). Then use **Append** transformation to combine them. This is faster than requesting all data in a single large query.</td></tr><tr><td><strong>Use Replace mode for complete refreshes</strong></td><td>If your destination doesn't need historical data, use **Replace** mode to overwrite old data instead of **Append**. This keeps your sheet or table smaller and faster to work with.</td></tr></tbody></table>

## Common pitfalls

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

* Test your API endpoint before creating a data flow
* Use **Path** to extract nested objects from API responses
* Select only the columns you actually need
* Add **Retries Count** and **Retries Delay** for flaky APIs
* Space out scheduled runs if the API has rate limits
* Verify authentication works (test in Postman first)
* Use query parameters to filter data at the source
  {% endcolumn %}

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

* Import every column if you only need a few (wastes time and space)
* Schedule multiple flows to hit the same API simultaneously
* Skip the manual test run — always verify before scheduling
* Ignore API rate limits (it will cause failures and blocks)
* Paste your actual API key or credentials in test messages
* Hardcode pagination offsets if the API supports bulk requests
* Assume the API response structure without checking with Postman first
  {% endcolumn %}
  {% endcolumns %}

{% hint style="danger" %}
**Never commit API keys to version control or share them in unencrypted messages.** Store authentication credentials securely in Coupler.io's **Request headers** field only.
{% endhint %}

{% hint style="danger" %}
**Avoid creating data flows without testing the API first.** A broken configuration will fail silently on schedule and waste time troubleshooting. Always run a manual test and confirm data appears in your destination before scheduling.
{% endhint %}