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) and its kind must match insight_type. 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; the others draw a kind: trend spec (line/table want an interval, number/bar/pie usually don't).

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

configobject

Required

query is an explore spec — the same object POST /client/v1/data/query takes; the full grammar is on the Explore queries page and a per-type walkthrough on the Insight config reference. Any other key is stored verbatim as display settings and never read by the runner.

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

Visualization only. funnel draws a kind: funnel spec; the others draw a kind: trend spec (line/table want an interval, number/bar/pie usually don't).

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?