Overview
Overview of V4MOS.AI Google Analytics API
The V4MOS.AI Google Analytics API centralizes sessions, events, custom events, customers, products, and transactions data from Google Analytics 4 properties connected to your organization. All endpoints live under the /v1/google-analytics prefix and follow the same authentication, pagination, and response patterns used across the platform.
Available Endpoints
- getSessions
/v1/google-analytics/sessionsRetrieve Google Analytics sessions with campaign, page, and traffic source metrics. - getEvents
/v1/google-analytics/eventsRetrieve Google Analytics events with engagement metrics. - getCustom Events
/v1/google-analytics/custom-eventsRetrieve Google Analytics custom events with metric mappings. - getCustomers
/v1/google-analytics/customersRetrieve Google Analytics customer metrics with geographic and device segmentation. - getProducts
/v1/google-analytics/productsRetrieve Google Analytics e-commerce product metrics. - getTransactions
/v1/google-analytics/transactionsRetrieve Google Analytics transaction metrics. - getEngagement
/v1/google-analytics/engagementSite engagement of the period from GA4: sessions, engaged sessions, bounce rate and average engagement time per session per day, in total… - getEvents by device
/v1/google-analytics/events-by-deviceGA4 events of the period summed per event and device category, for the audit (carts addtocart, purchases purchase, leads formsubmit, ...). - getProducts by device
/v1/google-analytics/products-by-deviceGA4 product funnel of the period summed per device category, for the audit: product views, carts, checkouts, purchases and item revenue,… - getLanding sessions
/v1/google-analytics/landing-sessionsGA4 sessions of the period by default channel group and by landing page, with the previous window (the same number of days right before…
Authentication
Every endpoint requires the organizationId query parameter. All endpoints except the audit routes (/events-by-device, /products-by-device and /landing-sessions) authenticate with the x-client-id and x-client-secret headers; the audit routes accept only a Bearer token (details below, in the by-device routes). See Authentication.
Common Parameters
organizationId(required) – Organization that owns the Google Analytics integrationuserId– User scopepage– Page number (default: 1)limit– Records per page (default: 500, max: 5000)createdStart/createdEnd– Filter by date range (ISO 8601)
Resource-Specific Filters
Sessions (/v1/google-analytics/sessions)
createdStart/createdEnd
Events (/v1/google-analytics/events)
createdStart/createdEnd
Custom Events (/v1/google-analytics/custom-events)
createdStart/createdEnd
Customers (/v1/google-analytics/customers)
createdStart/createdEnd
Products (/v1/google-analytics/products)
createdStart/createdEnd
Transactions (/v1/google-analytics/transactions)
createdStart/createdEnd
Engagement (/v1/google-analytics/engagement)
startDate/endDate(required,YYYY-MM-DD, UTC, up to 366 days); no pagination- Returns sessions, engaged sessions and bounce rate (
(1 - engaged sessions / sessions) * 100) per day, in total and per device engagementSeconds: GA4's average engagement time per session in seconds (userEngagementDuration / sessions:SUM(user_engagement_duration) / SUM(sessions), over the rows that carry the measure only); in a period only partly backfilled it is the average of the measured days, while sessions and bounce rate count every day;nullfor GA4 data loaded before the engagement-time backfill
Events by device (/v1/google-analytics/events-by-device)
startDate/endDate(required,YYYY-MM-DD, UTC, up to 366 days); optionaleventNames(comma-separated, up to 50); no pagination- Returns per event (e.g.
add_to_cart,purchase,form_submit) its event count, key events, event value and transactions in the period, in total and per device
Products by device (/v1/google-analytics/products-by-device)
startDate/endDate(required,YYYY-MM-DD, UTC, up to 366 days); no pagination- Returns product views, carts, checkouts, purchases and item revenue of the period over every product, in total and per device
The two by-device routes are made for the audit: they only accept a Bearer token of kind user or oaclient issued for the V4MOS application. The x-client-id / x-client-secret pair and customer service accounts get 403.
Landing sessions (/v1/google-analytics/landing-sessions)
startDate/endDate(required,YYYY-MM-DD, UTC, up to 366 days); no pagination- Returns sessions, engaged sessions and bounce rate per default channel group (with the sessions of the previous window of the same length) and the 10 landing pages with more sessions
- Also made for the audit: the same access as the by-device routes (Bearer
useroroaclient; the pair and service accounts get 403)
Google Analytics Data Model Highlights
Sessions
- Campaign and traffic:
campaign_id,campaign_name,source_medium,session_source_medium - Page details:
page_title,page_path - Users and sessions:
sessions,total_users,new_users,engaged_sessions,sessions_per_user - Date:
date
Events
- Identity:
event_name,date - Metrics:
event_count,event_count_per_user,event_value,events_per_session,key_events
Custom Events
- Identity:
event_name,event_date - Metrics:
metric_name,metric_value - RD Station mapping:
custom_rd_action,custom_rd_asset_id,custom_rd_filter - Categorization:
custom_event_category,custom_event_label
Customers
- Campaign and segmentation:
campaign_id,campaign_name,device_category,source_medium - Geography:
city,region,country - Audience metrics:
active_users,total_users,sessions,engaged_sessions,bounce_rate - Revenue metrics:
purchase_revenue,total_revenue,total_purchases,purchaser_rate - Date:
date
Products
- Product identity:
item_id,item_name - Revenue and purchases:
item_revenue,items_purchased - Interaction metrics:
items_viewed,items_added_to_cart,items_checked_out,items_clicked_in_promotion,item_list_click_through_rate - Date:
date
Transactions
- Identity:
event_name,date - Metrics:
transactions,transactions_per_purchaser
Responses
All responses follow the standard format:
{
"data": [...],
"meta": {
"page": 1,
"limit": 500,
"hasNextPage": true,
"hasPreviousPage": false
}
}