Google Analytics Integration with SmythOS
Want your website data to work smarter? Connect SmythOS to Google Analytics (GA4) to empower your agents to fetch website analytics, generate custom reports, and automate data retrieval, bringing powerful insights directly into your operational workflows.
List of Google Analytics Components
Quickly compare Google Analytics components by what they do and their key I/O. Click any component name to jump directly to its detailed guide. Here’s what's available:
Component | Action Type | Summary | Key Inputs | Key Outputs | Use Case |
---|---|---|---|---|---|
Run Report | Read | Fetches a customized analytics report from a GA4 property. | required GA4_property_id , Body | rows , rowCount | Scheduled reporting, KPI tracking. |
Run Real-Time Report | Read | Generates a report of real-time event data from a GA4 property. | required GA4_property_id , Body | rows , rowCount | Monitoring live campaigns or site issues. |
Batch Run Reports | Read | Retrieves multiple standard analytics reports in a single API request. | required GA4_property_id , Body | reports | Generating comprehensive dashboards. |
Prerequisites
Before you begin the integration, please ensure you have the following:
- An active SmythOS account. (Sign up here.)
- A Google Account with at least "Viewer" permission for the Google Analytics 4 (GA4) property you wish to integrate.
- OAuth 2.0 credentials (
Client ID
andClient Secret
) from the Google Cloud Console. - The Authorized redirect URI for SmythOS:
https://app.smythos.com/oauth/google/callback
Getting Started With Google Analytics
The connection between SmythOS and Google Analytics is handled via OAuth 2.0. This requires a one-time setup in the Google Cloud Console to get your credentials.
Step 1: Get Your OAuth 2.0 Credentials from Google
-
Go to Google Cloud Console:
- Navigate to
https://console.cloud.google.com/
and select or create a project.
- Navigate to
-
Enable the Necessary APIs:
- In the search bar, find and Enable both the Google Analytics Data API and the Google Analytics Admin API.
-
Configure OAuth Consent Screen:
- Go to APIs & Services > OAuth consent screen.
- Choose External for User Type and click
Create
. - Fill in the required app information (App name, User support email, Developer contact).
- Scopes: Click
Add or Remove Scopes
, search for "analytics", and addhttps://www.googleapis.com/auth/analytics.readonly
. ClickUpdate
. - Test Users: Add the email addresses of the Google accounts that will authenticate (including your own).
-
Create OAuth Client ID:
- Go to APIs & Services > Credentials.
- Click
+ Create Credentials
and selectOAuth client ID
. - For Application type, select
Web application
. - Under Authorized redirect URIs, click
+ Add URI
and enterhttps://app.smythos.com/oauth/google/callback
. - Click
Create
.
-
Copy Your Credentials:
- A dialog will appear with Your Client ID and Your Client Secret.
- Copy both values immediately.
Secure Your Credentials!
Step 2: Authenticate in SmythOS
- Add a Google Analytics Component: Drag any Google Analytics component onto your agent graph in SmythOS.
- Enter Credentials:
- Click the component to open its Settings.
- Input the
Client ID
andClient Secret
you just copied (or reference them from the Vault).
- Authorize the Connection:
- Click the
Authenticate
button. - You'll be redirected to a Google sign-in page. Log in and grant the requested permissions.
- You will be redirected back to SmythOS, and the integration will show as connected.
- Click the
Which Google Analytics Component Should I Use?
If you need to… | Typical Target / Key Inputs | Use this Component | Why this one? |
---|---|---|---|
Get a standard historical report (e.g., weekly traffic) | GA4_property_id , Body with dateRanges , dimensions , metrics | Run Report | Core component for most GA4 reporting needs on historical data. |
See active users right now | GA4_property_id , Body with metrics: [{"name": "activeUsers"}] | Run Real-Time Report | Specifically designed for immediate, up-to-the-minute data. |
Generate several reports at once (e.g., for a dashboard) | GA4_property_id , Body with a requests array of multiple report definitions | Batch Run Reports | More efficient than multiple "Run Report" calls. |
Track a specific campaign | GA4_property_id , Body with dateRanges and a dimensionFilter for the campaign | Run Report | Allows detailed segmentation and filtering. |
Component Details
This section provides detailed information for each Google Analytics component.
Run Report
Fetches a standard analytics report from your GA4 property by defining dimensions, metrics, date ranges, and filters.
Inputs
Field | Type | Required | Description |
---|---|---|---|
GA4_property_id | string | Yes | Your GA4 Property ID (e.g., properties/123456789 ). |
Body | object | Yes | A JSON object defining the report, including dateRanges , dimensions , and metrics . |
Outputs
Field | Type | Description |
---|---|---|
rows | array | Parsed array of data rows, each containing dimensionValues and metricValues . |
rowCount | integer | The number of rows returned in the report. |
Response | object | The full, raw JSON response from the Google Analytics Data API. |
Headers | object | The HTTP headers from the API response. |
{
"component": "googleAnalytics.runReport",
"GA4_property_id": "properties/123456789",
"Body": {
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"dimensions": [{"name": "sessionSourceMedium"}],
"metrics": [{"name": "sessions"}]
}
}
Run Real-Time Report
Generates a report of real-time event data from your GA4 property, providing immediate insights into user activity.
Inputs
Field | Type | Required | Description |
---|---|---|---|
GA4_property_id | string | Yes | Your GA4 Property ID (e.g., properties/123456789 ). |
Body | object | Yes | A JSON object defining the real-time report, including dimensions and metrics . |
Outputs
Field | Type | Description |
---|---|---|
rows | array | Parsed array of data rows containing real-time dimensionValues and metricValues . |
rowCount | integer | The number of rows in the real-time report. |
Response | object | The full, raw JSON response from the API. |
Headers | object | The HTTP headers from the API response. |
{
"component": "googleAnalytics.runRealtimeReport",
"GA4_property_id": "properties/123456789",
"Body": {
"dimensions": [{"name": "city"}],
"metrics": [{"name": "activeUsers"}]
}
}
Batch Run Reports
Retrieves multiple standard analytics reports in a single, efficient API request.
Inputs
Field | Type | Required | Description |
---|---|---|---|
GA4_property_id | string | Yes | Your GA4 Property ID (e.g., properties/123456789 ). |
Body | object | Yes | A JSON object containing a requests array. Each element in the array is a full report definition, like the body of the "Run Report" component. |
Outputs
Field | Type | Description |
---|---|---|
reports | array | Parsed array of report objects. Each object corresponds to a requested report and contains its own rows , rowCount , etc. |
Response | object | The full, raw JSON response from the API, containing the reports array. |
Headers | object | The HTTP headers from the API response. |
{
"component": "googleAnalytics.batchRunReports",
"GA4_property_id": "properties/123456789",
"Body": {
"requests": [
{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [{"name": "country"}],
"metrics": [{"name": "activeUsers"}]
},
{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [{"name": "deviceCategory"}],
"metrics": [{"name": "sessions"}]
}
]
}
}
Best Practices & Advanced Tips
- Secure Your Credentials: Always use the SmythOS
Vault
to store yourClient ID
andClient Secret
. - Understand GA4 Quotas: Be mindful of the Google Analytics Data API quotas to avoid service interruptions. Use
Batch Run Reports
to consolidate requests where possible. - Use Specific Dimensions & Metrics: To optimize performance and cost, only request the dimensions and metrics you need for your analysis.
- Implement Pagination: For reports that may return a large number of rows, use the
offset
andlimit
parameters in the requestBody
to paginate through the results.
Troubleshooting Common Issues
-
Authentication Errors (
invalid_client
,redirect_uri_mismatch
):- Cause: Incorrect
Client ID
/Secret
or a misconfigured redirect URI. - Solution: Verify your credentials. Ensure the redirect URI in Google Cloud Console is exactly
https://app.smythos.com/oauth/google/callback
.
- Cause: Incorrect
-
Permission Denied (
403 Forbidden
):- Cause: The authenticated user lacks "Viewer" permissions for the GA4 property, or the required API scopes were not granted.
- Solution: Confirm the user has adequate permissions in the GA4 Admin panel. Ensure the
analytics.readonly
scope was added and consented to during authentication.
-
Invalid Argument (
400 Bad Request
):- Cause: The
GA4_property_id
is formatted incorrectly, or a dimension/metric name is invalid or misspelled. - Solution: Ensure the property ID is
properties/YOUR_ID
. Check all dimension and metric names against the official GA4 Data API documentation.
- Cause: The
-
No Data Returned (
rowCount
is 0):- Cause: The GA4 property genuinely has no data for the requested query, or filters are too restrictive.
- Solution: Verify that data exists for the same query in the GA4 Explore reports. Try a broader date range or simpler dimensions to test the connection.
What's Next?
You are now ready to build powerful, data-driven workflows with the SmythOS Google Analytics Integration!
Consider these ideas:
- Build an Agent That...
- Sends a daily performance snapshot (key metrics like
activeUsers
,sessions
, andconversions
) to a Slack channel. - Monitors real-time active users and triggers an alert if traffic drops below a certain threshold.
- Generates a comprehensive monthly report by fetching multiple datasets with
Batch Run Reports
and writing them to a Google Sheet.
- Sends a daily performance snapshot (key metrics like
- Explore Other Integrations:
- Combine GA4 data with the Ahrefs Integration to correlate SEO efforts with traffic changes.
- Feed website conversion data into a CRM via other SmythOS connectors to track the full customer journey.