GA4 Insights API

All endpoints require authentication. Property management endpoints require agents tool permission. The query endpoint proxies requests to the Insights Agent Worker.

GA4 Properties

List Properties

GET /api/ga4-properties?search={term}&company_id={id}&environment={env}&limit={n}

Returns GA4 properties matching the filters. All parameters are optional.

Query parameters:

Param	Type	Description
search	string	Search by slug, display name, or exact property ID
company_id	string	Filter by Nucleus company ID
environment	string	Filter by production, staging, or testing
limit	number	Max results (default: 50)

Response:

{
  "properties": [
    {
      "id": "uuid",
      "slug": "ripcurl-au-ga4",
      "property_id": "257988737",
      "display_name": "Ripcurl Au Ga4",
      "company_id": null,
      "account_id": null,
      "environment": "production",
      "is_active": 1,
      "last_queried_at": "2026-04-22T10:30:00Z",
      "created_at": "2026-04-22T00:00:00",
      "updated_at": "2026-04-22T00:00:00"
    }
  ]
}

---

Get Property

GET /api/ga4-properties/{id}

Returns a single property by ID.

---

Create Property

POST /api/ga4-properties
Content-Type: application/json

{
  "slug": "newbrand-au-ga4",
  "property_id": "123456789",
  "display_name": "New Brand AU",
  "company_id": "optional-company-id",
  "environment": "production"
}

Required fields: slug, property_id

---

Update Property

PUT /api/ga4-properties/{id}
Content-Type: application/json

{ "display_name": "Updated Name", "company_id": "company-123" }

Allowed fields: slug, property_id, display_name, company_id, account_id, environment, is_active, last_queried_at

---

Delete Property

DELETE /api/ga4-properties/{id}

---

Discover Properties

POST /api/ga4-properties/discover

Auto-discovers GA4 properties from the Google Analytics Admin API using the Nucleus service account. Returns discovered properties without inserting them.

Response:

{
  "discovered": [
    {
      "slug": "auto-generated-slug",
      "property_id": "123456789",
      "display_name": "Property Display Name",
      "account_name": "GA4 Account Name"
    }
  ],
  "count": 42
}

---

Bulk Import Properties

POST /api/ga4-properties/import
Content-Type: application/json

{
  "properties": {
    "ripcurl-au-ga4": "257988737",
    "frank-green-au-ga4": "321515122"
  }
}

Bulk imports properties from a slug-to-property-ID mapping. Skips duplicates (INSERT OR IGNORE). Automatically infers environment from slug (contains staging/stg = staging, test/dev = testing, else production).

Response:

{ "ok": true, "imported": 278, "skipped": 0 }

---

GA4 Insights Query

Query Analytics

POST /api/ga4-insights/query
Content-Type: application/json

{
  "property": "ripcurl-au-ga4",
  "query_type": "devices",
  "days": 30
}

Proxies the query to the Insights Agent Worker, which fetches data from the GA4 Data API and returns AI-analysed insights.

Request body:

Field	Type	Required	Description
property	string	Yes	Property slug or GA4 property ID
query_type	string	Yes	One of: traffic, overview, content, devices, ecommerce, campaigns, countries, realtime, custom
question	string	For custom	Natural language question
days	number	No	Lookback period (default: 28)
start_date	string	No	Start date (YYYY-MM-DD), overrides days
end_date	string	No	End date (YYYY-MM-DD), overrides days
compare	boolean	No	Compare to previous period (default: true for overview)
filter	string	No	Dimension filter (e.g. country:Australia)
limit	number	No	Max rows (default: 20)

Response:

{
  "ok": true,
  "analysis": "AI-generated analysis text with insights and recommendations...",
  "data": { "dimensionHeaders": [...], "metricHeaders": [...], "rows": [...] }
}

MCP Tools

The Insights Agent exposes two MCP tools via the Nucleus MCP server:

Tool	Description
list_ga4_properties	List/search available GA4 properties
query_ga4_insights	Query GA4 data with AI analysis

These are available to any MCP client connected to mcp.nucleus.fast.