# Connecting Data Sources

Learn how to connect Google Analytics 4, Search Console, Google Ads, GitHub, and other platforms to AI Data Stream.

AI Data Stream connects to your analytics and marketing platforms so the AI can analyze your data in real-time. This guide covers each connection type.

## Connection Overview

| Data Source | Free | Pro | Business | Authentication |
|-------------|------|-----|----------|----------------|
| Google Analytics 4 | Yes | Yes | Yes | OAuth |
| Google Search Console | Yes | Yes | Yes | OAuth |
| PageSpeed Insights | Yes | Yes | Yes | None (public) |
| Google Ads | - | Yes | Yes | OAuth |
| WordPress | - | Yes | Yes | Application Password |
| HubSpot | - | - | Yes | Private App Token |
| GitHub | - | Yes | Yes | OAuth / Personal Access Token |
| Pipedrive | - | - | Yes | API Key |

All connections are **read-only**. We never modify your data.

---

## Google Analytics 4

GA4 is the most common connection. It provides website traffic, user behavior, conversions, and ecommerce data.

### Connecting GA4

1. Go to your property and click **Add Connection**
2. Select **Google Analytics 4**
3. Click **Connect with Google**
4. Sign in with your Google account (use the account that has GA4 access)
5. Review the permissions and click **Allow**
6. Select which GA4 properties to connect
7. Click **Confirm**

### What We Access

- **Traffic metrics:** Sessions, users, pageviews, bounce rate
- **Acquisition data:** Traffic sources, campaigns, referrals
- **Behavior:** Pages per session, avg. session duration
- **Conversions:** Goals, events, ecommerce transactions
- **Demographics:** Country, device, browser

### Permissions Required

We request:

- `analytics.readonly` - Read-only access to your Analytics data

We do NOT request write access.

### Troubleshooting

**"No properties found"**

- Ensure you're signing in with the correct Google account
- Check that your account has at least Viewer access to the GA4 property

**"Access denied"**

- The account owner may need to grant you access in GA4 Admin → Property Access

---

## Google Search Console

Search Console provides organic search data: clicks, impressions, keywords, and page rankings.

### Connecting Search Console

1. Go to your property and click **Add Connection**
2. Select **Google Search Console**
3. Click **Connect with Google**
4. Authorize access
5. Select which Search Console properties to connect

### Property Types

Search Console has two property types:

- **Domain properties** (e.g., `example.com`) - Includes all subdomains
- **URL-prefix properties** (e.g., `https://www.example.com/`) - Specific URLs only

Both work with AI Data Stream. Choose whichever you have set up.

### What We Access

- **Search performance:** Clicks, impressions, CTR, average position
- **Query data:** Keywords driving traffic
- **Page data:** Which pages rank and get clicks
- **Device breakdown:** Mobile, desktop, tablet performance

---

## PageSpeed Insights

PageSpeed provides Core Web Vitals and performance scores. No authentication required—it uses public data.

### Connecting PageSpeed

1. Go to your property and click **Add Connection**
2. Select **PageSpeed Insights**
3. Enter your website URL
4. Click **Connect**

### What We Access

- **Lighthouse scores:** Performance, Accessibility, Best Practices, SEO
- **Core Web Vitals:** LCP, FID, CLS
- **Performance metrics:** Speed Index, Time to Interactive
- **Opportunities:** Suggested improvements

---

## Google Ads

Available on **Pro and Business plans**. Connect your Google Ads account to analyze campaign performance.

### Before You Connect

Google Ads API access requires approval from Google. If you haven't already:

1. Your Google Ads account must be in good standing
2. API access is typically auto-approved for standard accounts
3. MCC (Manager) accounts can connect all sub-accounts

### Connecting Google Ads

1. Go to your property and click **Add Connection**
2. Select **Google Ads**
3. Click **Connect with Google**
4. Sign in with your Google Ads account
5. Select which accounts to connect (if you have multiple)
6. Click **Confirm**

### What We Access

- **Campaign performance:** Impressions, clicks, conversions, cost
- **Ad group data:** Performance by ad group
- **Keyword data:** Search terms, Quality Score
- **Conversion tracking:** Goals and values
- **Budget and spend:** Current spend vs budget

---

## WordPress

Available on **Pro and Business plans**. Connect WordPress to include content data in your analysis.

### Connecting WordPress

Works with any WordPress site running version 5.6 or later (Application Passwords are built-in).

1. Go to your property and click **Add Connection**
2. Select **WordPress**
3. Enter your WordPress site URL
4. Generate an Application Password in WordPress:
   - Go to WordPress Admin → Users → Your Profile
   - Scroll to "Application Passwords"
   - Enter "AI Data Stream" as the application name
   - Click "Add New Application Password"
   - Copy the password (you won't see it again)
5. Enter your WordPress username and paste the Application Password
6. Click **Connect**

### What We Access

- **Content:** Posts, pages, custom post types
- **Categories and tags:** Content organization
- **Authors:** Who published what
- **Dates:** Published and modified dates

---

## GitHub

Available on **Pro and Business plans**. Connect a GitHub repository to correlate code changes, deployments, and releases with your analytics data.

### Authentication Options

GitHub supports two authentication methods:

**Option A: OAuth (recommended)**

1. Go to your property and click **Add Connection**
2. Select **GitHub**
3. Click **Connect with GitHub**
4. Authorize AI Data Stream to access your repositories
5. Enter the repository owner and name
6. Click **Confirm**

**Option B: Personal Access Token**

1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
2. Click **Generate new token (classic)**
3. Name it "AI Data Stream"
4. Select the `repo` scope
5. Click **Generate token** and copy it
6. In AI Data Stream, select **GitHub** and choose **Personal Access Token**
7. Paste the token, enter the repository owner and name
8. Click **Connect**

### What We Access

- **Repository overview:** Language, stars, forks, visibility, license, topics
- **Releases:** Tag names, publication dates, release notes
- **Recent commits:** Commit messages, authors, dates (filterable by branch, date range, or author)
- **Commit activity:** Weekly commit frequency for the last 52 weeks
- **Deployments:** Production/staging deployments with status and environment
- **Issues:** Open/closed issues with labels, assignees, timestamps
- **Pull requests:** Merged/open/closed PRs with branch info, merge dates, and labels

### Tool Configuration

Each GitHub tool can be individually enabled or disabled in your connection settings. The repository overview is always available; the other six tools (releases, commits, commit activity, deployments, issues, pull requests) can be toggled based on what you need.

### Use Cases

GitHub is particularly powerful when combined with analytics data:

- **Deployment correlation:** "Did the traffic drop coincide with a deployment?"
- **Release impact:** "How did traffic change after the v2.0 release?"
- **Bug tracking:** "Are there open issues that could explain the conversion decrease?"
- **Development velocity:** "How does our commit frequency trend compare to traffic growth?"

---

## HubSpot

Available on **Business plans**. Connect HubSpot CRM to analyze deals, contacts, and pipeline health.

### Creating a Private App Token

1. Log in to your HubSpot account
2. Go to **Settings → Integrations → Private Apps**
3. Click **Create a private app**
4. Name it "AI Data Stream"
5. Under **Scopes**, grant read access to: CRM (contacts, companies, deals), Sales (activities, pipelines)
6. Click **Create app**
7. Copy the access token

### Connecting HubSpot

1. Go to your property and click **Add Connection**
2. Select **HubSpot**
3. Paste your Private App access token
4. Click **Connect**

### What We Access

- **Deals:** Pipeline, stages, values, close dates
- **Contacts:** Lead sources, lifecycle stages
- **Companies:** Associated deals and contacts
- **Activities:** Tasks, calls, emails logged
- **Pipeline metrics:** Win rates, deal velocity

---

## Pipedrive

Available on **Business plans**. Connect Pipedrive to analyze your sales pipeline and activities.

### Connecting Pipedrive

1. Go to your property and click **Add Connection**
2. Select **Pipedrive**
3. Enter your Pipedrive API token:
   - In Pipedrive: Settings → Personal preferences → API
   - Copy your personal API token
4. Paste the token in AI Data Stream
5. Click **Connect**

### What We Access

- **Deals:** Pipeline stages, values, probabilities
- **Activities:** Calls, meetings, tasks
- **Persons and organizations:** Contact data
- **Pipeline health:** Conversion rates, deal aging
- **Products:** If using Pipedrive products

---

## Managing Connections

### Viewing Connection Status

Each connection shows:

- **Active/Inactive** toggle
- **Last synced** timestamp
- **Error status** if there are issues

### Refreshing Connections

Data is queried in real-time, but if you need to refresh OAuth tokens:

1. Go to your property's **Connections** tab
2. Click the connection you want to refresh
3. Click **Reconnect** to re-authenticate

### Removing Connections

1. Go to **Connections**
2. Click the connection to remove
3. Click **Delete Connection**
4. Confirm the removal

This doesn't affect your data in the original platform.

### Connection Settings

Each connection has settings that control how it appears in the app:

**Show on Dashboard**

- Toggle whether this connection's widgets appear on your property dashboard
- Useful for hiding connections you don't need to monitor daily

**Show in Chat**

- Toggle whether this connection is enabled by default in AI Chat
- When disabled, the AI won't query this data source unless you manually enable it in a conversation
- Helps reduce context and focus on specific data sources
- You can always override these defaults within individual conversations

To change these settings:

1. Go to your property's **Connections** tab
2. Find the connection you want to configure
3. Click the dashboard icon (📊) to toggle dashboard visibility
4. Click the chat icon (💬) to toggle chat visibility
5. Or click **Edit** for more options

---

## Troubleshooting

### OAuth Errors

**"Access token expired"**

- Click **Reconnect** to re-authenticate

**"Insufficient permissions"**

- Ensure your account has the required access level
- For GA4/GSC: At least Viewer role
- For Google Ads: Standard or Admin access

### Connection Timeouts

**"Connection timed out"**

- Large data sets may take longer
- Try asking for a shorter date range

### Data Not Appearing

**"No data found"**

- Check that the date range has data
- Verify the correct property is connected
- For new connections, wait a few minutes for initial sync

### Rate Limits

**"Rate limit exceeded"**

- Too many requests to the platform
- Wait a few minutes and try again
- Consider combining queries

## Next Steps

- [Start a conversation with your data](/docs/using-ai-chat/)
- [Add annotations for context](/docs/annotations/)
- [Run reports on your data](/docs/reports/)