> For the complete documentation index, see [llms.txt](https://docs.smaq.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smaq.io/documentation/connections/connections.md).

# Overview

A **connection** is an authenticated link between your SMAQ project and an external data source. Most connections use OAuth — sign in with the platform, grant SMAQ read-only access, done. SQL databases use direct connection strings instead.

### What's supported

#### Ad platforms

| Platform                                                           | Auth             | Notes                                                           |
| ------------------------------------------------------------------ | ---------------- | --------------------------------------------------------------- |
| [Google Ads](/documentation/connections/google-ads.md)             | OAuth            | Search, Display, YouTube, Demand Gen — all under one connection |
| [Facebook Ads](/documentation/connections/facebook-ads.md)         | OAuth            | Includes Instagram ad placements via the same Meta connection   |
| [Instagram](/documentation/connections/instagram.md)               | OAuth            | Organic Instagram content & insights — separate from ads        |
| [TikTok Ads](/documentation/connections/tiktok-ads.md)             | OAuth            | TikTok for Business                                             |
| [LinkedIn Ads](/documentation/connections/linkedin-ads.md)         | OAuth            | Sponsored content & message ads                                 |
| [Apple Search Ads](/documentation/connections/apple-search-ads.md) | API key or OAuth | iOS App Store campaigns                                         |
| [DV360](/documentation/connections/dv360.md)                       | OAuth            | Display & Video 360 — programmatic                              |

#### Analytics & search

| Platform                                                                     | Auth  | Notes                                          |
| ---------------------------------------------------------------------------- | ----- | ---------------------------------------------- |
| [Google Analytics 4](/documentation/connections/ga4.md)                      | OAuth | Web & app analytics; supports ecommerce events |
| [Google Search Console](/documentation/connections/google-search-console.md) | OAuth | Organic search performance                     |

#### Social

| Platform                                                     | Auth  | Notes                                       |
| ------------------------------------------------------------ | ----- | ------------------------------------------- |
| [Facebook Page](/documentation/connections/facebook-page.md) | OAuth | Organic Facebook page insights              |
| [Threads](/documentation/connections/threads.md)             | OAuth | Meta Threads — organic content & engagement |

#### Attribution & ecommerce

| Platform                                                 | Auth      | Notes                                             |
| -------------------------------------------------------- | --------- | ------------------------------------------------- |
| [AppsFlyer](/documentation/connections/appsflyer.md)     | API token | Mobile attribution                                |
| [WooCommerce](/documentation/connections/woocommerce.md) | API key   | Shopify alternative — orders, products, customers |

#### Databases & custom

| Source                                                           | Auth                    | Notes                                                                 |
| ---------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| [SQL databases](/documentation/connections/sql-databases.md)     | Connection string       | PostgreSQL, MySQL, BigQuery, ClickHouse, Microsoft Azure SQL, MongoDB |
| [Custom endpoint](/documentation/connections/custom-endpoint.md) | API key / bearer / none | Any JSON HTTP endpoint                                                |

### What SMAQ does with the data

Once connected, SMAQ:

* Pulls data on-demand when datablocks are fetched and dashboards refreshed.
* Caches recent results to keep your dashboard interactive.
* Runs scheduled automations against the connection.
* Never writes back to your platform. Connections are read-only.

### What you'll need

* **OAuth platforms**: a login with the right account access. For ad platforms, you need at least read access to the ad account, property, or page you want to pull from.
* **API key platforms**: the API key from the platform's developer/admin settings.
* **SQL databases**: hostname, port, database name, username, password, and (for hosted databases) IP allowlist permission for SMAQ's outbound IPs.

### How to add a connection

1. Open your project and click **Data Source** in the side menu.
2. Click **Add data source** (or **Add your first data source** if it's your first).
3. Pick the platform.
4. Follow the platform-specific flow. The per-integration guides linked above walk through each one.

<figure><img src="/files/vZj7RYA67I0keOAA1RVY" alt=""><figcaption></figcaption></figure>

### Naming convention

When SMAQ asks you to name the connection, follow the pattern `Company - Source` — e.g. "Acme Co - Google Ads". When you have 10+ connections across projects, you'll be glad you did.

### Revoking access

SMAQ never holds permanent access to your platform. To revoke:

* **OAuth platforms**: revoke from the platform's app permissions (Google Account, Meta Business Suite, etc.). Your SMAQ connection will fail on next refresh and prompt you to reconnect.
* **API key platforms**: regenerate or delete the API key in the source platform.
* **From SMAQ**: open the connection, click **Delete**. The connection and any datablocks built on it are removed.

### Troubleshooting

* **"Connection failed" after OAuth** — usually a scope or account-access issue. Re-run the flow and double-check you're authorizing with an account that has access to the right ad account / property / page.
* **Data looks stale** — refresh the connection from the Data Source list (look for the refresh icon on the connection card).
* **Need to swap accounts** — easier to delete and re-add than to edit the connection.

If you hit something the per-integration guides don't cover, email **<info@smaq.io>**.


---

# 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.smaq.io/documentation/connections/connections.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.