Site Data Integration

skill

Read, create, and update Site Data records through its REST API using an org Integration row.

Download .md

Site Data Integration

When to use

Use this skill whenever a task requires reading web analytics for a site (visitors, pageviews, traffic sources, heatmaps, realtime activity, goals, funnels, or uptime), or when a site record itself needs to be created, updated, listed, or removed in Site Data. Typical triggers: a report asking for traffic trends, a request to check whether a site is currently up, a request to register a new site for tracking, or a downstream agent needing a site's api_key/domain_key before it can push events.

Tools

  • http-get — read-only calls (list/fetch sites, overview, breakdown, heatmap, confetti, realtime, goals, funnels, uptime)
  • http-post — create a new site
  • http-request — update (PATCH) or delete (DELETE) an existing site
  • write-file — stage large result sets (breakdowns, confetti data, incident lists) instead of inlining them
  • send-message — escalate to a human on auth failure, missing Integration, or ambiguous site identity

Playbook

  1. Resolve which site you are working with. Call http-get on /api/v1/sites to list all sites owned by the authenticated user and match by name or domain. If the site does not exist yet and the task calls for tracking a new domain, call http-post on /api/v1/sites to create it (or return the existing one matching that domain) — capture the returned id, api_key, and domain_key.
  2. To confirm or refresh details for a known site, call http-get on /api/v1/sites/:id.
  3. For a traffic summary (visitors, pageviews, sessions) over a period, call http-get on /api/v1/sites/:id/overview, passing the requested period as query parameters.
  4. For a breakdown by dimension (source, page, device, etc.), call http-get on /api/v1/sites/:id/breakdown with the dimension and period as query parameters.
  5. For click/scroll heatmap data, first call http-get on /api/v1/sites/:id/heatmap/pages to see which pages have data, then call http-get on /api/v1/sites/:id/heatmap for the chosen page. For individual click events, use http-get on /api/v1/sites/:id/confetti.
  6. For live visitor activity, call http-get on /api/v1/sites/:site_id/stats/realtime.
  7. For conversion tracking, call http-get on /api/v1/sites/:site_id/stats/goals for goals or /api/v1/sites/:site_id/stats/funnels for funnel stats.
  8. For availability monitoring, call http-get on /api/v1/sites/:site_id/stats/uptime for the current status summary, and /api/v1/sites/:site_id/stats/uptime/incidents for the incident history.
  9. To rename a site, change its domain, or update its timezone, use http-request with PATCH against /api/v1/sites/:id.
  10. To decommission a site, use http-request with DELETE against /api/v1/sites/:id. Confirm this is intended before deleting — it is destructive.
  11. When any response set is large (long breakdown tables, confetti event dumps, multi-day incident logs), use write-file to stage the raw payload before summarizing it, rather than pasting it inline.

Failure modes

  • 401 or 403 on any call: stop immediately, do not retry, and use send-message to notify a human, naming "Site Data" as the app and stating that the integration's credentials need the sites read/write scope re-checked.
  • No Integration row configured for Site Data in the org: use send-message to ask a human to add one before proceeding — do not fabricate a base URL or API key.
  • Ambiguous or missing site identity (name/domain doesn't match any listed site): re-list sites with http-get on /api/v1/sites and, if still unresolved, use send-message to ask a human to confirm which site is intended rather than guessing an id.
  • Empty or zeroed analytics response: treat as a valid "no traffic in period" result, not an error — do not retry the same call repeatedly.

Done when

The requested site data has been fetched, summarized, or staged via write-file, or the requested site record has been created, updated, or deleted and its confirmation (id, api_key/domain_key, or deletion acknowledgment) has been reported back.