Google Analytics

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

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 integration
  • userId – User scope
  • page – 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; null for 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); optional eventNames (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 user or oaclient; 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
  }
}

On this page