Insightful Pipe

---

name: insightfulpipe description: "Query and manage marketing data across 40+ platforms — Google Analytics, Google Ads, Facebook Ads, Instagram, Shopify, HubSpot, Klaviyo, TikTok, LinkedIn, and more." homepage: https://insightfulpipe.com metadata: { "openclaw": { "emoji": "📊", "requires": { "bins": ["insightfulpipe"], "env": ["INSIGHTFULPIPE_TOKEN"] }, "install": [ { "id": "node", "kind": "node", "package": "insightfulpipe", "bins": ["insightfulpipe"], "label": "Install InsightfulPipe CLI (npm)", }, ], }, }

---

Install InsightfulPipe if it doesn't exist

npm install -g insightfulpipe

npm release: https://www.npmjs.com/package/insightfulpipe

---

| Property | Value | |----------|-------| | name | insightfulpipe | | description | Query marketing data across analytics, ads, social, ecommerce, and SEO platforms | | allowed-tools | Bash(insightfulpipe:*) |

---

Authentication

The INSIGHTFULPIPE_TOKEN environment variable is expected to be pre-configured. If a command fails with "Invalid token" or "Not authenticated", inform the user that their token needs to be configured.

---

Core Workflow

Every query follows: discover → schema → execute. Read operations (query) can run directly. Write operations (action) should be confirmed with the user before executing.

# 1. Get account IDs (workspace_id, brand_id, source IDs)
insightfulpipe accounts --platform  --json
2. See available actions
insightfulpipe helper 
3. Get request body schema for specific actions
insightfulpipe helper  --actions ,
4. Execute read query
insightfulpipe query  -b '{"action":"","workspace_id":,"brand_id":,...}'
5. Execute write operation (requires --yes)
insightfulpipe action  -b '{"action":"",...}' --yes

---

Platform Examples

Google Analytics — Top Pages

insightfulpipe accounts --platform google-analytics --json
insightfulpipe helper google-analytics --actions pages
insightfulpipe query google-analytics -b '{
  "action": "pages",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["pagePath"],
  "metrics": ["screenPageViews", "activeUsers"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "limit": 10
}'

Google Analytics — Traffic Sources

insightfulpipe query google-analytics -b '{
  "action": "traffic_sources",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["sessionSource", "sessionMedium"],
  "metrics": ["sessions", "totalUsers", "bounceRate"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20"
}'

Google Analytics — Freeform Report

insightfulpipe query google-analytics -b '{
  "action": "get_report",
  "workspace_id": xxx,
  "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["date", "country"],
  "metrics": ["activeUsers", "sessions"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20"
}'

Google Search Console — Top Queries

insightfulpipe query google-search-console -b '{
  "action": "search_analytics",
  "workspace_id": xxx,
  "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["query"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "row_limit": 10
}'

Google Search Console — Pages by Country

insightfulpipe query google-search-console -b '{
  "action": "search_analytics",
  "workspace_id": xxx,
  "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["page", "country"],
  "start_date": "2026-03-01",
  "end_date": "2026-03-20",
  "row_limit": 20
}'

Google Sheets — Peek at Columns Then Query

# First peek to see column names
insightfulpipe query google-sheets -b '{
  "action": "get_sheet_peak",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0"
}'
Then query with filters using exact column names from peek
insightfulpipe query google-sheets -b '{
  "action": "query_sheet_data",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0",
  "select": "Name,Email,Status",
  "where": "Status=Active",
  "limit": 50
}'

Google Sheets — Write Cells

insightfulpipe action google-sheets -b '{
  "action": "update_cells",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "sheet_id": "0",
  "range": "A1:C2",
  "values": [["Name", "Email", "Status"], ["John", "john@example.com", "Active"]]
}' --yes

Shopify — Recent Orders

insightfulpipe query shopify -b '{
  "action": "get_orders",
  "workspace_id": xxx,
  "brand_id": xxx,
  "status": "any",
  "limit": 10
}'

Shopify — Products

insightfulpipe query shopify -b '{
  "action": "get_products",
  "workspace_id": xxx,
  "brand_id": xxx,
  "limit": 10
}'

Any Other Platform

# Same pattern works for all platforms:
insightfulpipe helper                         # See actions
insightfulpipe helper  --actions      # Get body schema
insightfulpipe query  -b '{...}'              # Execute

Supported platforms include: facebook-ads, instagram, tiktok-ads, tiktok-pages, linkedin-ads, linkedin-pages, hubspot, klaviyo, mailchimp, stripe, slack, telegram, and many more. Run insightfulpipe platforms to see the full list.

---

Common Patterns

Pattern 1: Pipe to jq

# Extract just page paths from GA response
insightfulpipe query google-analytics -b '{...}' | jq '.data[].pagePath'
Get total sessions
insightfulpipe query google-analytics -b '{...}' | jq '[.data[].sessions] | add'

Pattern 2: Compare Data Across Platforms

# GA traffic
GA=$(insightfulpipe query google-analytics -b '{
  "action": "traffic_sources", "workspace_id": xxx, "brand_id": xxx,
  "property_id": "properties/xxx",
  "dimensions": ["sessionSource"], "metrics": ["sessions"],
  "start_date": "2026-03-01", "end_date": "2026-03-20"
}')
GSC queries
GSC=$(insightfulpipe query google-search-console -b '{
  "action": "search_analytics", "workspace_id": xxx, "brand_id": xxx,
  "site_url": "https://example.com/",
  "dimensions": ["query"],
  "start_date": "2026-03-01", "end_date": "2026-03-20", "row_limit": 10
}')
echo "$GA" | jq '.data[:5]'
echo "$GSC" | jq '.data[:5]'

Pattern 3: Write Operations

# Always use "action" (not "query") and --yes for writes
insightfulpipe action google-sheets -b '{
  "action": "create_sheet",
  "workspace_id": xxx,
  "brand_id": xxx,
  "spreadsheet_id": "xxx",
  "title": "New Sheet"
}' --yes

Pattern 4: Use Prompts for Guided Analysis

insightfulpipe prompts google-analytics            # List templates
insightfulpipe prompts google-analytics --id 12    # Get specific prompt

---

Gotchas

1. Never guess the request body — always run helper --actions first. 2. Replace ALL "xxx" placeholders — get real values from accounts --platform --json. 3. GA property_id needs "properties/" prefix — use "properties/510157516" not "510157516". 4. Date format is YYYY-MM-DD — use "2026-03-20" not "2026-03-20T00:00:00Z". 5. Use query for reads, action --yes for writes — using the wrong one will fail. 6. Google Sheets: peek before query — call get_sheet_peak first to see column names. 7. Different platforms have different source IDs — GA uses property_id, GSC uses site_url, Shopify uses shop_domain, Facebook Ads uses ad_account_id. 8. Empty data is not an error — {"status":"success","data":[]} means no data matched your filters. 9. Token should be pre-configured — if auth fails, inform the user to check their token configuration. 10. Confirm write operations with the user — always ask before running insightfulpipe action. Read operations via insightfulpipe query are safe to run directly.

---

All Commands

# Discovery
insightfulpipe platforms                              # All supported platforms
insightfulpipe accounts --platform  --json  # Account IDs
insightfulpipe sources --platform           # Sources with IDs
insightfulpipe brands --workspace                 # Brand metadata
insightfulpipe whoami                                 # Current user
insightfulpipe doctor                                 # Check auth
Schema
insightfulpipe helper                       # List actions
insightfulpipe helper  --actions ,  # Body schema
Execute
insightfulpipe query  -b ''           # Read data
insightfulpipe query  -f file.json          # Read from file
insightfulpipe action  -b '' --yes    # Write data
Prompts
insightfulpipe prompts                      # List templates
insightfulpipe prompts  --id            # Get prompt