Data API

Overview

The Data API is a read-only surface for agencies that want to pull Mythic Analytics event data into their own systems. It serves aggregated event analytics — summaries, daily counts, and volume trends — plus the provisioning status of a BigQuery export.

Every endpoint is a GET except POST /query, whose body is a query spec. CORS is open for GET, POST and OPTIONS, which is what lets the Builder embed's own pickers read events and property values — but keys remain server-side credentials: treat one that reaches a browser you don't control as compromised.

Base URL

All endpoints share the same base URL.

https://mythic-analytics.gulp.workers.dev/client/v1/data

Location scoping

Event data is isolated per location. How the location is determined depends on the key type:

The event routes are location-scoped. The /export route is agency-wide and requires an agency key. See Authentication for details.

Endpoints

Before you explain a drop-off

GET /explain/coverage?page=/pricing answers one question: is there enough data here to support a conclusion? It returns no analysis. Call it first — and if you are driving this API from an AI agent, hand the response through verbatim rather than summarising it.

The reason is that the dangerous output is not a bad number, it is a number that should never have been computed. On a real paid landing page with 4,225 non-bot sessions over 14 days, zero of them fired the conversion event — because the page carries no form. Its step is a click-through to the next page. A conversion rate there reads 0.00%, and the obvious recommendation ("rewrite this page") is wrong.

Three evidence arms are reported, always all three, so you can distinguish "checked and unavailable" from "not checked". An arm is available only when both sides of its contrast hold at least min_arm_n sessions.

Counts are page-scoped and order-scoped. An exception thrown two pages later is evidence about that step, not this one — and "advanced" requires a page after this one, not just a second page somewhere in the session. On the reference page 17 of 521 sessions saw their other page only before it: a 3% error on a landing page, approaching 100% on a mid-funnel page where every visitor arrives from somewhere else. Bots are excluded, which matters more than it sounds — unfiltered, that page reads 4,834 sessions instead of 4,225, and the whole 12.6% inflation lands in the denominator.

When answerable is true but every arm with coverage carries a confound, a top-level caveat of only_confounded_arms_available says so. Branch on that field rather than inferring it from the arm list.

curl -s -H "Authorization: Bearer $MYTHIC_KEY" \
  -H "X-Location-Id: $LOCATION_ID" \
  "https://mythic-analytics.gulp.workers.dev/client/v1/data/explain/coverage?page=/pricing&outcome_event=form_submitted"

{
  "success": true,
  "data": {
    "page": "/pricing",
    "window_days": 14,
    "answerable": false,
    "reason": "outcome_event_never_fires",
    "hint": "No session on /pricing fired "form_submitted" in 14d. This is missing instrumentation or the wrong step definition, NOT a 0% conversion rate — omit outcome_event to measure page-transition instead.",
    "outcome": {
      "kind": "event",
      "event": "form_submitted",
      "n_positive": 0,
      "n_total": 4225
    },
    "arms": [
      {
        "id": "error_outcome",
        "available": true,
        "n": 190,
        "mde_pp": 6.7,
        "confound": "exposure",
        "confound_note": "Throwing a client-side error requires engaging with the page, so this arm measures exposure. Hold dwell/interaction depth fixed before reading it."
      },
      { "id": "field_abandon", "available": false, "n": 0, "reason": "no_form_on_page" },
      {
        "id": "scroll_contrast",
        "available": false,
        "n": 7,
        "coverage": 0.0017,
        "reason": "too_few_scroll_sessions",
        "hint": "Scroll capture is opt-in per location — enable capture_heatmaps for this client and wait for traffic."
      }
    ],
    "thresholds": { "min_arm_n": 30, "min_scroll_coverage": 0.05 }
  }
}

A false here is a useful answer, not an error. It tells you which pages to turn heatmap capture on for, and which conversion events are missing from a funnel you thought you were measuring.

Response envelope

Every response is a JSON envelope with a success flag.

Example error response:

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Missing authorization"
  }
}

Rate limiting

Requests are limited to 120 per 10 seconds per location. When you exceed the limit you receive a 429 with a Retry-After header. Successful responses also carry X-RateLimit-Limit and X-RateLimit-Remaining headers.

Error handling