Validate a config (no query)

Shape check for an insight config — no query runs. Applies the same rules as the write path: config.query must be a valid explore spec (unknown keys, limits, date ranges, maths, filters) whose kind fits insight_type, or config.analysis must name a known kind with allowlisted params. Requires an agency key (ak_) and ?location_id=. Use it on every edit; run /insights/preview when you also need data.

curl -X POST "https://mythic-analytics.gulp.workers.dev/builder/insights/validate?location_id=acme-retail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": {
        "preset": "30d"
      },
      "interval": "day",
      "series": [
        {
          "event": "$pageview",
          "math": "dau",
          "label": "Visitors"
        }
      ],
      "compare": "previous_period"
    }
  }
}'

import requests
import json

url = "https://mythic-analytics.gulp.workers.dev/builder/insights/validate?location_id=acme-retail"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": {
        "preset": "30d"
      },
      "interval": "day",
      "series": [
        {
          "event": "$pageview",
          "math": "dau",
          "label": "Visitors"
        }
      ],
      "compare": "previous_period"
    }
  }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://mythic-analytics.gulp.workers.dev/builder/insights/validate?location_id=acme-retail", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
},
  body: JSON.stringify({
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": {
        "preset": "30d"
      },
      "interval": "day",
      "series": [
        {
          "event": "$pageview",
          "math": "dau",
          "label": "Visitors"
        }
      ],
      "compare": "previous_period"
    }
  }
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": {
        "preset": "30d"
      },
      "interval": "day",
      "series": [
        {
          "event": "$pageview",
          "math": "dau",
          "label": "Visitors"
        }
      ],
      "compare": "previous_period"
    }
  }
}`)

    req, err := http.NewRequest("POST", "https://mythic-analytics.gulp.workers.dev/builder/insights/validate?location_id=acme-retail", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://mythic-analytics.gulp.workers.dev/builder/insights/validate?location_id=acme-retail')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": {
        "preset": "30d"
      },
      "interval": "day",
      "series": [
        {
          "event": "$pageview",
          "math": "dau",
          "label": "Visitors"
        }
      ],
      "compare": "previous_period"
    }
  }
}'

response = http.request(request)
puts response.body

{
  "ok": false,
  "errors": [
    "insight_type "line" cannot draw a "funnel" query"
  ]
}

{
  "error": "Bad Request",
  "message": "The request contains invalid parameters or malformed data",
  "code": 400,
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

POST

/insights/validate

POST

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

Builder key as a bearer token. Use an agency key (Bearer ak_...) for writes, or a viewer key (Bearer sk_...) for reads. Scoped keys (mcp_) with insights:read/insights:write are accepted too.

query

location_idstring

Client location to scope the request to. Required when authenticating with an agency key (ak_). Ignored for viewer keys (sk_).

Content-Typestring

Required

The media type of the request body

Options: application/json

insight_typestring

Required

Visualization only. funnel draws a kind: funnel spec; table, bar and number can also draw kind: attribution; the others draw a kind: trend spec (line/table want an interval, number/bar/pie usually don't). Analysis panels: constraints → table/number/bar, correlation → line/table, scanner_summary → pie/bar/line/table/number.

Options: number, line, bar, pie, table, funnel

configobject

Required

Exactly one of query or analysis. query is an explore spec — the same object POST /client/v1/data/query takes (trend, funnel, or attribution for ad spend, CPA and ROAS); the full grammar is on the Explore queries page and a per-type walkthrough on the Insight config reference. analysis runs a constraint finder, correlation or scanner summary as the viewer (not on public or embedded dashboards). Any other key is stored verbatim as display settings and never read by the runner, except metric on an attribution number.

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. Builder key as a bearer token. Use an agency key (Bearer ak_...) for writes, or a viewer key (Bearer sk_...) for reads. Scoped keys (mcp_) with insights:read/insights:write are accepted too.

Query Parameters

location_idstring

Client location to scope the request to. Required when authenticating with an agency key (ak_). Ignored for viewer keys (sk_).

Example:

acme-retail

Body

application/json

insight_typestring

Required

Allowed values:numberlinebarpietablefunnel

configobject

Required

Example:

{"query":{"kind":"trend","date_range":{"preset":"30d"},"interval":"day","series":[{"event":"$pageview","math":"dau","label":"Visitors"}],"compare":"previous_period"}}

Responses

okboolean

errorsstring[]

Present only when ok is false.

Was this page helpful?