Developer API

Insights Paid Media, GA4, Search Console & Attribution API

Export paid media spend and conversions (Google Ads & Meta Ads), GA4 sessions and revenue, Google Search Console performance, and True Attribution outcomes.

The Insights endpoint aggregates connected paid media accounts, Google Analytics 4 properties, Google Search Console properties, and True Attribution conversion events (including email-attributed revenue) over your selected date range.

1. Insights & True Attribution Overview (GET /api/v1/insights/overview)

Endpoint: GET https://profilepilotapp.com/api/v1/insights/overview Required Scope: insights:read or reports:read Required Product Subscription: Insights + Developer API Access (note: true_attribution event rollups require an Insights DIWM or DIFM plan).

Query Parameters:

startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC).

Performance Metrics & Response Fields:

ad_accounts[] — Connected Google Ads and Meta Ads accounts ({ id, platform, account_id, name, status, currency }).
paid_media.totals — { impressions, clicks, cost, conversions, conversion_value, reach, store_interactions, ctr_pct, cpc, roas }.
paid_media.by_platform — Object keyed by ad platform (e.g. google_ads, meta_ads), each containing { impressions, clicks, cost, conversions, conversion_value, reach, store_interactions, roas }.
paid_media.top_campaigns[] — Top 25 campaigns sorted by spend ({ id, name, platform, status, impressions, clicks, cost, conversions, conversion_value, roas }).
ga4.totals — { total_users, new_users, active_users, sessions, engaged_sessions, screen_page_views, conversions, revenue, transactions, engagement_rate_pct } plus ga4.daily_rows (number).
search_console.totals — { clicks, impressions, ctr_pct, avg_position } (where avg_position is impression-weighted) plus search_console.daily_rows (number).
true_attribution — When subscribed to Insights DIWM/DIFM (entitled: true):
total_events (number), matched_events (number), match_rate_pct (number | null), total_attributed_value (number).
email_attributed: { events, revenue } — Conversions attributed to ProfilePilot Email Marketing campaigns and automated workflows.
by_outcome_type: Object keyed by conversion outcome (e.g. purchase, lead, whatsapp_order) with { count, value }.
by_channel: Object keyed by attributed channel label with { count, value }.

curl -sS -X GET "https://profilepilotapp.com/api/v1/insights/overview?startDate=2026-10-01&endDate=2026-10-20" \
  -H "Authorization: Bearer ppapi_your_secret_key"

{
  "ok": true,
  "period": { "startDate": "2026-10-01", "endDate": "2026-10-20" },
  "ad_accounts": [
    {
      "id": "ia_01",
      "platform": "google_ads",
      "account_id": "123-456-7890",
      "name": "Harbour Stores Search & PMax",
      "status": "ACTIVE",
      "currency": "ZAR"
    }
  ],
  "paid_media": {
    "totals": {
      "impressions": 1420000,
      "clicks": 38400,
      "cost": 84500.00,
      "conversions": 1240,
      "conversion_value": 612000.00,
      "reach": 490000,
      "store_interactions": 6120,
      "ctr_pct": 2.7,
      "cpc": 2.2,
      "roas": 7.24
    },
    "by_platform": {
      "google_ads": {
        "impressions": 810000,
        "clicks": 24100,
        "cost": 52000.00,
        "conversions": 810,
        "conversion_value": 410000.00,
        "reach": 0,
        "store_interactions": 4890,
        "roas": 7.88
      },
      "meta_ads": {
        "impressions": 610000,
        "clicks": 14300,
        "cost": 32500.00,
        "conversions": 430,
        "conversion_value": 202000.00,
        "reach": 490000,
        "store_interactions": 1230,
        "roas": 6.22
      }
    },
    "top_campaigns": [
      {
        "id": "camp_01",
        "name": "PMax - Western Cape Store Visits & Online",
        "platform": "google_ads",
        "status": "ENABLED",
        "impressions": 420000,
        "clicks": 14200,
        "cost": 28400.00,
        "conversions": 490,
        "conversion_value": 265000.00,
        "roas": 9.33
      }
    ]
  },
  "ga4": {
    "totals": {
      "total_users": 71500,
      "new_users": 48900,
      "active_users": 69200,
      "sessions": 94200,
      "engaged_sessions": 68400,
      "screen_page_views": 248000,
      "conversions": 1890,
      "revenue": 845200.00,
      "transactions": 1420,
      "engagement_rate_pct": 72.61
    },
    "daily_rows": 20
  },
  "search_console": {
    "totals": {
      "clicks": 41200,
      "impressions": 890000,
      "ctr_pct": 4.63,
      "avg_position": 8.4
    },
    "daily_rows": 20
  },
  "true_attribution": {
    "entitled": true,
    "total_events": 640,
    "matched_events": 512,
    "match_rate_pct": 80.0,
    "total_attributed_value": 790000.00,
    "email_attributed": {
      "events": 148,
      "revenue": 164500.00
    },
    "by_outcome_type": {
      "purchase": { "count": 490, "value": 712000.00 },
      "whatsapp_order": { "count": 150, "value": 78000.00 }
    },
    "by_channel": {
      "Google Ads": { "count": 220, "value": 340000.00 },
      "Email Marketing": { "count": 148, "value": 164500.00 },
      "Meta Ads": { "count": 144, "value": 195500.00 }
    }
  }
}

2. Troubleshooting & Common Scenarios

`true_attribution.entitled` is `false`: The Insights DIY Data Feed tier covers Paid Media, GA4, and Search Console reporting. True Attribution cross-channel and email revenue matching requires an Insights DIWM or DIFM plan.
Zero rows in `ga4` or `search_console`: Confirm that your Google Analytics 4 property and Google Search Console site are connected under Marketing → Insights → Settings and that the daily sync has completed (daily_rows > 0).

Typical Tasks

Grant insights:read scope to your API key in Settings → Developer API
Call GET /api/v1/insights/overview with startDate and endDate
Combine paid_media, ga4, search_console, and true_attribution in your executive BI models

Developer API Reference

All Developer & Reporting API Modules

Manage API Keys →

Store Sync

locations:readlocations:write

Enterprise Store Locations API

Push and query your canonical store master records (up to 100 stores per batch) by store_code.

POST/api/v1/locations

GET/api/v1/locations

GET/api/v1/locations/{store_code}

DELETE/api/v1/locations/{store_code}

Local Presence & SEO

reports:readlocations:read

Locations Metrics & Local SEO Geo-Grid API

Pull Google Business Profile impressions, website clicks, phone calls, direction requests, peak footfall days, Meta store metrics, and Geo-Grid Share of Voice.

GET/api/v1/reports/locations/metrics

GET/api/v1/reports/seo-grid

Reputation & CX

reputation:readreports:read

Reputation, Reviews, Red Flags & CSAT API

Export star ratings, customer reviews, reply rates, business-hours response times, Red Flag alerts, and Customer Satisfaction cases.

GET/api/v1/reports/reputation/summary

GET/api/v1/reputation/reviews

GET/api/v1/reputation/red-flags

GET/api/v1/reputation/csat

WhatsApp Commerce

whatsapp:readreports:read

WhatsApp Commerce, Orders, Finance & Usage API

Export WhatsApp orders with normalized line items, fulfilment SLAs, paid GMV analytics, metered message volume, Auth OTP challenges, and loyalty balances.

GET/api/v1/whatsapp/orders

GET/api/v1/whatsapp/orders/{id}

GET/api/v1/whatsapp/reports/finance

GET/api/v1/whatsapp/reports/usage

Email & Marketing

email:readmarketing:readreports:read