QueriesRun a saved insight

Run a saved insight

Execute a saved insight, optionally overriding its date range and interval for this run. Results are cached server-side — a window that ends before today is reused for hours, one touching today for two minutes — and rate-limited per location (120/min across the authed Builder paths).

Readable with an agency key (ak_, requires ?location_id=) or a viewer key (sk_).

curl -X POST "https://mythic-analytics.gulp.workers.dev/builder/insights/123e4567-e89b-12d3-a456-426614174000/query?location_id=acme-retail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "dateRange": {
    "preset": "24h",
    "from": "2024-12-25",
    "to": "2024-12-25"
  },
  "granularity": "hour"
}'
{
  "success": true,
  "insight": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "insight_type": "number",
    "config": {}
  },
  "engine": "tinybird",
  "kind": "trend",
  "buckets": [
    "example_string"
  ],
  "previous_buckets": [
    "example_string"
  ],
  "series": [
    {
      "label": "example_string",
      "math": "example_string",
      "event": "example_string",
      "breakdown_value": "example_string",
      "data": [
        3.14
      ],
      "total": 3.14,
      "value": 3.14,
      "previous": [
        3.14
      ],
      "previous_value": 3.14
    }
  ],
  "breakdown_values": [
    "example_string"
  ],
  "steps": [
    {
      "step": 42,
      "label": "example_string",
      "event": "example_string",
      "users": 42,
      "conversion_from_first": 3.14,
      "conversion_from_previous": 3.14
    }
  ],
  "breakdown": [
    {
      "value": "example_string",
      "steps": [
        {
          "step": 42,
          "label": "example_string",
          "event": "example_string",
          "users": 42,
          "conversion_from_first": 3.14,
          "conversion_from_previous": 3.14
        }
      ]
    }
  ],
  "meta": {},
  "config": {},
  "cached": true,
  "sql": "example_string"
}
POST
/insights/{id}/query
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_...) or a viewer key (Bearer sk_...). Scoped keys (mcp_) with insights:read are accepted too.

Builder key as a bearer token. Use an agency key (Bearer ak_...) or a viewer key (Bearer sk_...). Scoped keys (mcp_) with insights:read are accepted too.
path
idstring
Required

Insight UUID (must belong to the resolved location).

Format: uuid
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
dateRangeobject

Date range override, applied onto config.query.date_range for this run only. An unknown preset leaves the stored range in place.

granularitystring

Bucket interval override, applied onto config.query.interval. Trends only — a funnel never gains an interval.

Options: hour, day, week, month
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_...) or a viewer key (Bearer sk_...). Scoped keys (mcp_) with insights:read are accepted too.

Path Parameters

idstring
Required

Insight UUID (must belong to the resolved location).

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
dateRangeobject

Date range override, applied onto config.query.date_range for this run only. An unknown preset leaves the stored range in place.

granularitystring

Bucket interval override, applied onto config.query.interval. Trends only — a funnel never gains an interval.

Allowed values:hourdayweekmonth

Responses

successboolean
insightobject

The insight's definition (for rendering).

enginestring
Allowed values:tinybird
kindstring
Allowed values:trendfunnel
bucketsstring[]

Trend with interval — ISO bucket labels (UTC).

previous_bucketsstring[]

Trend with interval and compare.

seriesarray

Trend only.

breakdown_valuesstring[]

Trend with breakdown — values in rank order, $$other last.

stepsarray

Funnel only.

breakdownarray

Funnel with breakdown — per-value step rows.

metaobject

Resolved from/to, to_exclusive (where a window that includes today actually stopped), the previous window (truncated to the same time of day), interval, window_seconds, grain (funnels: what a step counted), breakdown settings, and query statistics (sql_ms, rows_read, bytes_read).

configobject

The stored config, echoed.

cachedboolean

True when served from the server-side cache.

sqlstring

The compiled query. Returned on the key-authed POST /insights/{id}/query runner and /insights/preview, but NOT on the anonymous POST /public/query endpoint.