{"openapi":"3.0.3","info":{"title":"Steep API","description":"API documentation","version":"1.0.0"},"paths":{"/v1/metrics":{"get":{"description":"List metrics for your workspace. Use for broader catalog exploration. For targeted discovery, prefer metric search over scanning this list.","tags":["metrics"],"x-steep":{"requiredScopes":["metrics:read"],"exposeUnderMCP":true},"parameters":[{"name":"expand","in":"query","required":false,"schema":{"default":"false","description":"Boolean string. When `true`, populates `dimensions`, `module`, `slices`, `cohort`, `owners`, `category`, `filters`, and `teamIdsWithAccess`. When `false`, those fields are `null`. Avoid `expand=true` unless filtering by `identifiers`, as an expanded full-catalog response can be large.","type":"string","format":"boolean"}},{"name":"identifiers","in":"query","required":false,"schema":{"description":"Filter to metrics with these exact `metric.identifier`s (Readable semantic model keys).","examples":[["revenue","order_count"]],"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"link":{"type":"string","description":"A link to the metric in the app"},"isPrivate":{"type":"boolean"},"teamIdsWithAccess":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`."},"isUnlisted":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dimensions":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","enum":["string-or-boolean","city","country","time","h3-cell-index"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","type","description"],"additionalProperties":false}},{"type":"null"}],"description":"Dimensions for this metric. Populated when `expand=true`; otherwise `null`."},"module":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"table":{"type":"string"},"schema":{"type":"string"},"externalSource":{"anyOf":[{"type":"string","enum":["dbt-cloud","cube","code"]},{"type":"null"}]}},"required":["id","label","description","identifier","table","schema","externalSource"],"additionalProperties":false,"title":"Module"},{"type":"null"}],"description":"Module for this metric. Populated when `expand=true`; otherwise `null`."},"slices":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter":{"anyOf":[{"type":"object","properties":{"column":{"type":"string"},"operator":{"type":"string","enum":["equals","not-equals","less-than","less-than-or-equal","greater-than","greater-than-or-equal","in","not-in","is","is-not","like","not-like"]},"expression":{"type":"string"}},"required":["column","operator","expression"],"additionalProperties":false},{"type":"null"}]}},"required":["id","label","filter"],"additionalProperties":false}},{"type":"null"}],"description":"Slices for this metric. Populated when `expand=true`; otherwise `null`."},"cohort":{"anyOf":[{"type":"object","properties":{"deltaTimeCalculationType":{"anyOf":[{"type":"string","const":"calendar-periods"},{"type":"string","const":"rolling-periods"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"calculateRetention":{"description":"% of initial value.","anyOf":[{"type":"boolean"},{"type":"null"}]},"timeGrains":{"anyOf":[{"type":"array","items":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]}},{"type":"null"}]},"time":{"type":"string"}},"required":["deltaTimeCalculationType","time"],"additionalProperties":false},{"type":"null"}],"description":"Cohort for this metric. Populated when `expand=true`; otherwise `null`."},"owners":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Category name for this metric. Populated when `expand=true`; otherwise `null`."},"timeResampling":{"anyOf":[{"type":"string","enum":["sum/divide","average/repeat"]},{"type":"null"}]},"timeGrains":{"anyOf":[{"type":"array","items":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]}},{"type":"null"}]},"filters":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"operator":{"type":"string","enum":["equals","not-equals","less-than","less-than-or-equal","greater-than","greater-than-or-equal","in","not-in","is","is-not","like","not-like"]},"expression":{"type":"string"}},"required":["column","operator","expression"],"additionalProperties":false}},{"type":"null"}],"description":"Filters for this metric. Populated when `expand=true`; otherwise `null`."}},"required":["id","identifier","label","description","link","isPrivate","teamIdsWithAccess","isUnlisted","updatedAt","dimensions","module","slices","cohort","owners","category","timeResampling","timeGrains","filters"],"additionalProperties":false},{"oneOf":[{"type":"object","properties":{"calculation":{"type":"string","const":"sum"},"value":{"type":"string"}},"required":["calculation","value"],"additionalProperties":false,"title":"Metric (sum)"},{"type":"object","properties":{"calculation":{"type":"string","const":"ratio"},"numerator":{"type":"string"},"denominator":{"type":"string"},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numerator","denominator","format"],"additionalProperties":false,"title":"Metric (ratio)"},{"type":"object","properties":{"calculation":{"type":"string","const":"count"}},"required":["calculation"],"additionalProperties":false,"title":"Metric (count)"},{"type":"object","properties":{"calculation":{"type":"string","const":"count-distinct"},"distinct_on":{"type":"string"}},"required":["calculation","distinct_on"],"additionalProperties":false,"title":"Metric (count distinct)"},{"type":"object","properties":{"calculation":{"type":"string","const":"custom-value"},"sqlExpression":{"type":"string"}},"required":["calculation","sqlExpression"],"additionalProperties":false,"title":"Metric (custom value)"},{"type":"object","properties":{"calculation":{"type":"string","const":"custom-ratio"},"numeratorSql":{"anyOf":[{"type":"string"},{"type":"null"}]},"denominatorSql":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numeratorSql","denominatorSql","format"],"additionalProperties":false,"title":"Metric (custom ratio)"},{"type":"object","properties":{"calculation":{"type":"string","const":"derived-ratio"},"numeratorMetricId":{"type":"string","description":"`id` of the metric used as the numerator"},"denominatorMetricId":{"type":"string","description":"`id` of the metric used as the denominator"},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numeratorMetricId","denominatorMetricId","format"],"additionalProperties":false,"title":"Metric (derived ratio)"}]}],"title":"Metric"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1Metrics"}},"/v1/metrics/search":{"get":{"description":"Search metrics by keywords. Returns relevance-ranked search hits. Get further details via get metric by `id`, or list metrics filtered by `identifiers`.","tags":["metrics"],"x-steep":{"requiredScopes":["metrics:read"],"exposeUnderMCP":true},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search keywords."}},{"name":"limit","in":"query","required":false,"schema":{"default":10,"description":"Maximum number of hits to return.","type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"label":{"type":"string"},"link":{"type":"string"},"descriptionPreview":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Up to 200 characters of the metric description."}},"required":["id","identifier","label","link","descriptionPreview"],"additionalProperties":false,"title":"Metric search hit"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1MetricsSearch"}},"/v1/metrics/{metricId}":{"get":{"description":"Get a single metric by `id`.","tags":["metrics"],"x-steep":{"requiredScopes":["metrics:read"],"exposeUnderMCP":true},"parameters":[{"name":"metricId","in":"path","required":true,"schema":{"type":"string","description":"`metric.id` — Unique resource ID (opaque)."}},{"name":"expand","in":"query","required":false,"schema":{"default":"false","description":"Boolean string. When `true`, populates `dimensions`, `module`, `slices`, `cohort`, `owners`, `category`, `filters`, and `teamIdsWithAccess`. When `false`, those fields are `null`.","type":"string","format":"boolean"}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"link":{"type":"string","description":"A link to the metric in the app"},"isPrivate":{"type":"boolean"},"teamIdsWithAccess":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Team `id`s with access to this metric. Populated when `expand=true` for private metrics; otherwise `null`."},"isUnlisted":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"dimensions":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string","enum":["string-or-boolean","city","country","time","h3-cell-index"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","label","type","description"],"additionalProperties":false}},{"type":"null"}],"description":"Dimensions for this metric. Populated when `expand=true`; otherwise `null`."},"module":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"table":{"type":"string"},"schema":{"type":"string"},"externalSource":{"anyOf":[{"type":"string","enum":["dbt-cloud","cube","code"]},{"type":"null"}]}},"required":["id","label","description","identifier","table","schema","externalSource"],"additionalProperties":false,"title":"Module"},{"type":"null"}],"description":"Module for this metric. Populated when `expand=true`; otherwise `null`."},"slices":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"filter":{"anyOf":[{"type":"object","properties":{"column":{"type":"string"},"operator":{"type":"string","enum":["equals","not-equals","less-than","less-than-or-equal","greater-than","greater-than-or-equal","in","not-in","is","is-not","like","not-like"]},"expression":{"type":"string"}},"required":["column","operator","expression"],"additionalProperties":false},{"type":"null"}]}},"required":["id","label","filter"],"additionalProperties":false}},{"type":"null"}],"description":"Slices for this metric. Populated when `expand=true`; otherwise `null`."},"cohort":{"anyOf":[{"type":"object","properties":{"deltaTimeCalculationType":{"anyOf":[{"type":"string","const":"calendar-periods"},{"type":"string","const":"rolling-periods"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"calculateRetention":{"description":"% of initial value.","anyOf":[{"type":"boolean"},{"type":"null"}]},"timeGrains":{"anyOf":[{"type":"array","items":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]}},{"type":"null"}]},"time":{"type":"string"}},"required":["deltaTimeCalculationType","time"],"additionalProperties":false},{"type":"null"}],"description":"Cohort for this metric. Populated when `expand=true`; otherwise `null`."},"owners":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Owner user `id`s for this metric. Match `id` from list workspace members. Populated when `expand=true`; otherwise `null`."},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Category name for this metric. Populated when `expand=true`; otherwise `null`."},"timeResampling":{"anyOf":[{"type":"string","enum":["sum/divide","average/repeat"]},{"type":"null"}]},"timeGrains":{"anyOf":[{"type":"array","items":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]}},{"type":"null"}]},"filters":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"operator":{"type":"string","enum":["equals","not-equals","less-than","less-than-or-equal","greater-than","greater-than-or-equal","in","not-in","is","is-not","like","not-like"]},"expression":{"type":"string"}},"required":["column","operator","expression"],"additionalProperties":false}},{"type":"null"}],"description":"Filters for this metric. Populated when `expand=true`; otherwise `null`."}},"required":["id","identifier","label","description","link","isPrivate","teamIdsWithAccess","isUnlisted","updatedAt","dimensions","module","slices","cohort","owners","category","timeResampling","timeGrains","filters"],"additionalProperties":false},{"oneOf":[{"type":"object","properties":{"calculation":{"type":"string","const":"sum"},"value":{"type":"string"}},"required":["calculation","value"],"additionalProperties":false,"title":"Metric (sum)"},{"type":"object","properties":{"calculation":{"type":"string","const":"ratio"},"numerator":{"type":"string"},"denominator":{"type":"string"},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numerator","denominator","format"],"additionalProperties":false,"title":"Metric (ratio)"},{"type":"object","properties":{"calculation":{"type":"string","const":"count"}},"required":["calculation"],"additionalProperties":false,"title":"Metric (count)"},{"type":"object","properties":{"calculation":{"type":"string","const":"count-distinct"},"distinct_on":{"type":"string"}},"required":["calculation","distinct_on"],"additionalProperties":false,"title":"Metric (count distinct)"},{"type":"object","properties":{"calculation":{"type":"string","const":"custom-value"},"sqlExpression":{"type":"string"}},"required":["calculation","sqlExpression"],"additionalProperties":false,"title":"Metric (custom value)"},{"type":"object","properties":{"calculation":{"type":"string","const":"custom-ratio"},"numeratorSql":{"anyOf":[{"type":"string"},{"type":"null"}]},"denominatorSql":{"anyOf":[{"type":"string"},{"type":"null"}]},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numeratorSql","denominatorSql","format"],"additionalProperties":false,"title":"Metric (custom ratio)"},{"type":"object","properties":{"calculation":{"type":"string","const":"derived-ratio"},"numeratorMetricId":{"type":"string","description":"`id` of the metric used as the numerator"},"denominatorMetricId":{"type":"string","description":"`id` of the metric used as the denominator"},"format":{"type":"string","enum":["number","percentage"]}},"required":["calculation","numeratorMetricId","denominatorMetricId","format"],"additionalProperties":false,"title":"Metric (derived ratio)"}]}],"title":"Metric"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1MetricsByMetricId"}},"/v1/metrics/{metricId}/query":{"post":{"description":"Query data for a metric, optionally for a specific slice. Returns metric values for the requested date range. Omit `timeGrain` for a single aggregate over the period; set it for time-series data. Supports breakdown dimensions and filters.","tags":["metrics"],"x-steep":{"requiredScopes":["metrics:read","dataqueries:read"],"exposeUnderMCP":true},"parameters":[{"name":"metricId","in":"path","required":true,"schema":{"type":"string","description":"`metric.id` — Unique resource ID (opaque)."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"timeGrain":{"description":"Time granularity for time-series results. Omit for a single aggregate snapshot result.","type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},"fromDate":{"type":"string","description":"Start of the query period. Pass any ISO 8601 date or date-time: a bare `2026-01-01` (read as UTC midnight), `2026-01-01T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-01-01","2026-01-01T00:00:00Z","2026-01-01T12:30:00+02:00"]},"toDate":{"type":"string","description":"End of the query period. Pass any ISO 8601 date or date-time: a bare `2026-12-31` (read as UTC midnight), `2026-12-31T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-12-31","2026-12-31T00:00:00Z","2026-12-31T23:59:59+02:00"]},"breakdownDimensionIds":{"description":"Dimension `id`s to break down by (max 2).","examples":[["country"]],"maxItems":2,"type":"array","items":{"type":"string"}},"sliceId":{"description":"Slice `id` to fetch query data for.","type":"string"},"filters":{"description":"Dimension filters to apply.","type":"array","items":{"type":"object","properties":{"dimensionId":{"type":"string","description":"Dimension `id` to filter by."},"filterValues":{"type":"array","items":{"type":"string"},"description":"Filter values for this dimension.","examples":[["US","UK"]]}},"required":["dimensionId","filterValues"],"additionalProperties":false}}},"required":["fromDate","toDate"],"additionalProperties":false}},"application/x-www-form-urlencoded":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"timeGrain":{"description":"Time granularity for time-series results. Omit for a single aggregate snapshot result.","type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},"fromDate":{"type":"string","description":"Start of the query period. Pass any ISO 8601 date or date-time: a bare `2026-01-01` (read as UTC midnight), `2026-01-01T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-01-01","2026-01-01T00:00:00Z","2026-01-01T12:30:00+02:00"]},"toDate":{"type":"string","description":"End of the query period. Pass any ISO 8601 date or date-time: a bare `2026-12-31` (read as UTC midnight), `2026-12-31T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-12-31","2026-12-31T00:00:00Z","2026-12-31T23:59:59+02:00"]},"breakdownDimensionIds":{"description":"Dimension `id`s to break down by (max 2).","examples":[["country"]],"maxItems":2,"type":"array","items":{"type":"string"}},"sliceId":{"description":"Slice `id` to fetch query data for.","type":"string"},"filters":{"description":"Dimension filters to apply.","type":"array","items":{"type":"object","properties":{"dimensionId":{"type":"string","description":"Dimension `id` to filter by."},"filterValues":{"type":"array","items":{"type":"string"},"description":"Filter values for this dimension.","examples":[["US","UK"]]}},"required":["dimensionId","filterValues"],"additionalProperties":false}}},"required":["fromDate","toDate"],"additionalProperties":false}},"multipart/form-data":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"timeGrain":{"description":"Time granularity for time-series results. Omit for a single aggregate snapshot result.","type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},"fromDate":{"type":"string","description":"Start of the query period. Pass any ISO 8601 date or date-time: a bare `2026-01-01` (read as UTC midnight), `2026-01-01T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-01-01","2026-01-01T00:00:00Z","2026-01-01T12:30:00+02:00"]},"toDate":{"type":"string","description":"End of the query period. Pass any ISO 8601 date or date-time: a bare `2026-12-31` (read as UTC midnight), `2026-12-31T00:00:00Z`, or with an offset like `+02:00` (converted to UTC).","examples":["2026-12-31","2026-12-31T00:00:00Z","2026-12-31T23:59:59+02:00"]},"breakdownDimensionIds":{"description":"Dimension `id`s to break down by (max 2).","examples":[["country"]],"maxItems":2,"type":"array","items":{"type":"string"}},"sliceId":{"description":"Slice `id` to fetch query data for.","type":"string"},"filters":{"description":"Dimension filters to apply.","type":"array","items":{"type":"object","properties":{"dimensionId":{"type":"string","description":"Dimension `id` to filter by."},"filterValues":{"type":"array","items":{"type":"string"},"description":"Filter values for this dimension.","examples":[["US","UK"]]}},"required":["dimensionId","filterValues"],"additionalProperties":false}}},"required":["fromDate","toDate"],"additionalProperties":false}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cacheTtlInSeconds":{"type":"number"},"refreshedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"sql":{"type":"string"},"total":{"type":"number","description":"Deprecated. Reflects the number of rows in `data`, not the total matching rows when the row limit is hit. Use `hasMore` and `limit` instead.","deprecated":true},"limit":{"type":"number","description":"The effective row limit applied to this query."},"hasMore":{"type":"boolean","description":"Indicates there is more data beyond the row limit."},"data":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"The time of the data point. Undefined if timeGrain is not provided."},"metric":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The metric value for the given time."}},"required":["metric"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Breakdown value","description":"Breakdown value for the given breakdown dimension. The field name matches the breakdown dimension identifier."},"title":"Data point"}}},"required":["cacheTtlInSeconds","refreshedAt","sql","total","limit","hasMore","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"postV1MetricsByMetricIdQuery"}},"/v1/targets":{"get":{"description":"List available target series and their metrics for your workspace. Use for broader target series exploration, or filter by metric `identifier` if metrics of interest are already known.","tags":["targets"],"x-steep":{"requiredScopes":["targets:read"],"exposeUnderMCP":true},"parameters":[{"name":"metricIdentifiers","in":"query","required":false,"schema":{"description":"Filter to targets for these exact `metric.identifier`s (Readable semantic model keys).","minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1}}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"targetSeries":{"type":"string"},"metricIdentifier":{"type":"string"},"timeGrain":{"anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"null"}]},"fromDate":{"type":"string"},"toDate":{"type":"string"},"rowCount":{"type":"number"},"dimensionValues":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"}]}},{"type":"null"}],"description":"Map of dimension identifier to value for this target row. Keys are dimension identifiers (e.g. \"country\", \"region\"). Null when the target has no dimension breakdown.","examples":[{"country":"US"}]}},"required":["targetSeries","metricIdentifier","timeGrain","fromDate","toDate","rowCount","dimensionValues"],"additionalProperties":false,"title":"Target row"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1Targets"}},"/v1/targets/query":{"post":{"description":"Query time-series target data for a metric and target series.","tags":["targets"],"x-steep":{"requiredScopes":["target-queries:read"],"exposeUnderMCP":true},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metricIdentifier":{"type":"string","description":"The `metric.identifier` to query targets for. Must match the `metricIdentifier` value returned when listing targets."},"targetSeries":{"type":"string","description":"The target series to query. Must match the `targetSeries` value returned when listing targets."},"breakdownDimensionIdentifier":{"description":"Dimension `identifier` to break down by. Use a key from a `dimensionValues` object returned when listing targets (`{ dimensionIdentifier: dimensionValue }`). Breakdown requires a non-empty matching entry in `dimensionFilters` for the same dimension `identifier`, with the values to include in the breakdown. Each filtered value becomes a separate data point.","examples":["country"],"type":"string"},"dimensionFilters":{"description":"Dimension filters to apply. Keys are dimension `identifier`s; values are allowed values. Derive both from `dimensionValues` returned when listing targets — e.g. `{ \"country\": \"US\" }` → `{ \"country\": [\"US\"] }`. When using `breakdownDimensionIdentifier`, include that dimension here too.","examples":[{"country":["US","UK"]}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"required":["metricIdentifier","targetSeries"],"additionalProperties":false}},"application/x-www-form-urlencoded":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metricIdentifier":{"type":"string","description":"The `metric.identifier` to query targets for. Must match the `metricIdentifier` value returned when listing targets."},"targetSeries":{"type":"string","description":"The target series to query. Must match the `targetSeries` value returned when listing targets."},"breakdownDimensionIdentifier":{"description":"Dimension `identifier` to break down by. Use a key from a `dimensionValues` object returned when listing targets (`{ dimensionIdentifier: dimensionValue }`). Breakdown requires a non-empty matching entry in `dimensionFilters` for the same dimension `identifier`, with the values to include in the breakdown. Each filtered value becomes a separate data point.","examples":["country"],"type":"string"},"dimensionFilters":{"description":"Dimension filters to apply. Keys are dimension `identifier`s; values are allowed values. Derive both from `dimensionValues` returned when listing targets — e.g. `{ \"country\": \"US\" }` → `{ \"country\": [\"US\"] }`. When using `breakdownDimensionIdentifier`, include that dimension here too.","examples":[{"country":["US","UK"]}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"required":["metricIdentifier","targetSeries"],"additionalProperties":false}},"multipart/form-data":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metricIdentifier":{"type":"string","description":"The `metric.identifier` to query targets for. Must match the `metricIdentifier` value returned when listing targets."},"targetSeries":{"type":"string","description":"The target series to query. Must match the `targetSeries` value returned when listing targets."},"breakdownDimensionIdentifier":{"description":"Dimension `identifier` to break down by. Use a key from a `dimensionValues` object returned when listing targets (`{ dimensionIdentifier: dimensionValue }`). Breakdown requires a non-empty matching entry in `dimensionFilters` for the same dimension `identifier`, with the values to include in the breakdown. Each filtered value becomes a separate data point.","examples":["country"],"type":"string"},"dimensionFilters":{"description":"Dimension filters to apply. Keys are dimension `identifier`s; values are allowed values. Derive both from `dimensionValues` returned when listing targets — e.g. `{ \"country\": \"US\" }` → `{ \"country\": [\"US\"] }`. When using `breakdownDimensionIdentifier`, include that dimension here too.","examples":[{"country":["US","UK"]}],"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"required":["metricIdentifier","targetSeries"],"additionalProperties":false}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"The time of the data point."},"value":{"type":"number","description":"The target value for the given time."}},"required":["time","value"],"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"title":"Target data point"}},"timeGrain":{"anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"null"}]},"cacheTtlInSeconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"limit":{"type":"number","description":"The effective row limit applied to this query."},"hasMore":{"type":"boolean","description":"Indicates there is more data beyond the row limit."}},"required":["data","timeGrain","cacheTtlInSeconds","limit","hasMore"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"postV1TargetsQuery"}},"/v1/entities":{"get":{"description":"List entities for your workspace.","tags":["entities"],"x-steep":{"requiredScopes":["entities:read"],"exposeUnderMCP":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"name":{"type":"string"},"moduleId":{"type":"string","description":"`id` of the module this entity belongs to."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","moduleId","createdAt","updatedAt"],"additionalProperties":false,"title":"Entity"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1Entities"}},"/v1/modules":{"get":{"description":"List modules for your workspace.","tags":["modules"],"x-steep":{"requiredScopes":["modules:read"],"exposeUnderMCP":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"identifier":{"type":"string","description":"Readable semantic model key. Used to cross-reference objects in the semantic model."},"table":{"type":"string"},"schema":{"type":"string"},"externalSource":{"anyOf":[{"type":"string","enum":["dbt-cloud","cube","code"]},{"type":"null"}]}},"required":["id","label","description","identifier","table","schema","externalSource"],"additionalProperties":false,"title":"Module"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1Modules"}},"/v1/reports":{"post":{"description":"Create a new report: a saved, shareable document that persists in the workspace as a lasting artifact to revisit or share. Build its body from the `blocks` field. Returns the new report's `id` and title.","tags":["reports"],"x-steep":{"requiredScopes":["reports:write"],"requiredFeatureFlags":["reports-in-ai"],"exposeUnderMCP":true},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Report title. Concise and descriptive."},"blocks":{"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"],"additionalProperties":false,"description":"A horizontal divider that separates sections of the report. Carries no content — use between groups of blocks to break up a long report."},{"type":"object","properties":{"type":{"type":"string","const":"layout"},"children":{"minItems":2,"maxItems":4,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."}]},"description":"The 2–4 content blocks rendered as equal-width columns, left to right."}},"required":["type","children"],"additionalProperties":false,"description":"A layout block that arranges 2–4 content blocks side by side as equal-width columns. Children must be content blocks (text, chart, big-number) — layout blocks cannot nest. Use for comparisons or related charts that read well next to each other."}]},"description":"Ordered list of blocks that make up the report body, in document order. Chart, table and big-number blocks reference metric `id`s from list metrics, search metrics, or get metric by `id`."}},"required":["title","blocks"],"additionalProperties":false}},"application/x-www-form-urlencoded":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Report title. Concise and descriptive."},"blocks":{"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"],"additionalProperties":false,"description":"A horizontal divider that separates sections of the report. Carries no content — use between groups of blocks to break up a long report."},{"type":"object","properties":{"type":{"type":"string","const":"layout"},"children":{"minItems":2,"maxItems":4,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."}]},"description":"The 2–4 content blocks rendered as equal-width columns, left to right."}},"required":["type","children"],"additionalProperties":false,"description":"A layout block that arranges 2–4 content blocks side by side as equal-width columns. Children must be content blocks (text, chart, big-number) — layout blocks cannot nest. Use for comparisons or related charts that read well next to each other."}]},"description":"Ordered list of blocks that make up the report body, in document order. Chart, table and big-number blocks reference metric `id`s from list metrics, search metrics, or get metric by `id`."}},"required":["title","blocks"],"additionalProperties":false}},"multipart/form-data":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"Report title. Concise and descriptive."},"blocks":{"maxItems":100,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"],"additionalProperties":false,"description":"A horizontal divider that separates sections of the report. Carries no content — use between groups of blocks to break up a long report."},{"type":"object","properties":{"type":{"type":"string","const":"layout"},"children":{"minItems":2,"maxItems":4,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"properties":{"type":"object","properties":{"body":{"type":"string","description":"Block content as GitHub-flavored Markdown — headings, paragraphs, lists, bold/italic, links, inline code, blockquotes, code blocks, and GFM pipe tables. Use tables for small comparisons; prefer chart blocks for trends over time. Converted to HTML before storage."}},"required":["body"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"chart"},"properties":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID to visualize."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"timeGrainMode":{"default":"auto","description":"Either an explicit grain, or 'auto' to let the system choose.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"dimensionSettings":{"type":"object","properties":{"breakdown":{"description":"Dimension ID used for breakdown. Required for rank charts.","type":"string"},"filters":{"default":{},"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["filters"],"additionalProperties":false,"description":"Breakdown and filter configuration."},"targetName":{"description":"When the user asks for targets, goals, or a target line: set this to the exact target series name from get-metric-targets (e.g. '2025 target', 'Forecast'). This draws the goal line.","type":"string"},"metrics":{"description":"Add one or more other, different metrics to compare (e.g. revenue vs costs). Do not add the same metric.","type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for the comparison series."},"sliceId":{"default":null,"description":"Optional slice/segment ID for the comparison series.","anyOf":[{"type":"string"},{"type":"null"}]},"applyFilters":{"type":"boolean","description":"Whether to apply the chart's dimension filters to this series."},"yAxis":{"type":"string","enum":["left","right"],"description":"Which Y-axis this comparison series should use."},"vizType":{"type":"string","enum":["line","bar"],"description":"How to render the comparison series."}},"required":["metricId","sliceId","applyFilters","yAxis","vizType"],"additionalProperties":false,"description":"Compare the primary metric to another, different metric (e.g. revenue vs costs, metric A vs metric B)."}},"compares":{"description":"Same-metric time comparisons (e.g. lag-1y, year-over-year for vs last year) or moving averages. last-period and x-over-x work when the user asks about a standard rolling period (last week, last month, last year, last 2 years, etc.). Do NOT use last-period or x-over-x when the user specifies an arbitrary explicit date range like 'Feb 2025 to Jul 2025' — the comparison will be silently ignored. For such ranges, use lag-1y or year-over-year instead, or omit functions and note the limitation in text.","type":"array","items":{"type":"string","enum":["min","max","avg","lag-1y","last-period","x-over-x","year-over-year","avg-7d","avg-28d","lag-1y-same-weekday","year-over-year-same-weekday"],"description":"Period-over-period comparisons and same-metric derivations, shown only on a line or bar chart. Use ONLY a comparison the metric reports in its `compares` hint (from SearchMetrics/GetMetricDetails) — e.g. ratio metrics exclude year-over-year/x-over-x, so use lag-1y there — and respect that hint's daily-grain constraints. lag-1y and year-over-year overlay the same period from last year; last-period overlays the absolute values of the previous period of equal length as a comparison series (use this when user asks 'last week vs previous week', 'last 2 years vs previous 2 years', etc.); x-over-x shows the percentage change vs the previous period as a separate line — these are mutually exclusive alternatives, do NOT add both, pick only the one the user is asking for; min/max/avg aggregate over the visible range; avg-7d/avg-28d are moving averages; lag-1y-same-weekday and year-over-year-same-weekday align by weekday for year comparisons."}},"cumulative":{"default":false,"description":"Show a running total over time. Only valid on a line or bar chart, and only when the metric's `cumulative` hint is `built-in` — for `expanding-window`/`already-cumulative`/`unsupported` metrics, leave this false.","type":"boolean"},"title":{"description":"Optional chart title to display above the visualization.","type":"string"},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown items.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown items to show (e.g. top 3). Rank charts allow up to 1000; other chart types cap at 50.","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' row.","type":"boolean"},"show100PercentBars":{"description":"Show bars as percentages (only relevant for some charts).","type":"boolean"}},"additionalProperties":false},"showValues":{"default":"none","type":"string","enum":["none","main-metric","all"],"description":"Value labels visibility. Displayed above the data points or bars."},"pivotTable":{"type":"object","properties":{"rows":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"cols":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"temporal"},"value":{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Time grain to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"categorical"},"value":{"type":"string","description":"Dimension ID to use on this axis."}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"total"}},"required":["type"],"additionalProperties":false}],"description":"Axis selection for pivot tables (rows/cols)."},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"totalsStyle":{"default":"none","description":"Whether to show row/column totals.","type":"string","enum":["none","rows-and-columns","columns","rows"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false}},"required":["tableStyle","totalsStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Pivot table configuration (rows/cols and rendering options)."},"cohortsTable":{"type":"object","properties":{"cohortId":{"description":"Cohort definition identifier.","type":"string"},"cohortTimeGrain":{"default":"auto","description":"Time grain used to bucket cohorts.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"deltaTimeGrain":{"default":"auto","description":"Time grain used for the delta/age axis.","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"],"description":"Granularity used to aggregate a time series."},{"type":"string","const":"auto"}]},"tableStyle":{"default":"values-and-colors","description":"How to render each cell (values, colors, or both).","type":"string","enum":["values-and-colors","colors","values"]},"colorScheme":{"default":"monochrome-blue","description":"Heatmap color palette.","type":"string","enum":["monochrome-blue","monochrome-pink","monochrome-green","monochrome-yellow","monochrome-purple","monochrome-red","monochrome-gray","traffic-lights","viridis","magma","red-blue","cyclic-blue"]},"colorSchemeFlipped":{"default":false,"description":"Invert the heatmap mapping (high values become low colors).","type":"boolean"},"colorThresholds":{"description":"Optional thresholds to control heatmap scaling.","type":"object","properties":{"min":{"description":"Lower bound for color scaling.","type":"number"},"mid":{"description":"Midpoint for diverging scales.","type":"number"},"max":{"description":"Upper bound for color scaling.","type":"number"}},"additionalProperties":false},"deltaTimeThresholds":{"description":"Optional [min, max] thresholds for the delta-time axis.","type":"array","prefixItems":[{"anyOf":[{"type":"number"},{"type":"null"}]},{"anyOf":[{"type":"number"},{"type":"null"}]}]}},"required":["cohortTimeGrain","deltaTimeGrain","tableStyle","colorScheme","colorSchemeFlipped"],"additionalProperties":false,"description":"Cohorts table configuration."},"chartType":{"type":"string","enum":["line","bar","rank","pivot-table","cohorts-table"],"description":"Visualization type: line/bar for trends over time, rank for top/bottom categories, pivot-table for cross-tab breakdowns, cohorts-table for retention/behavior cohorts. When breaking down an existing chart by a dimension, use the same chart type as the previously shown chart unless the user explicitly requests a different type."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["metricId","timeGrainMode","cumulative","showValues","chartType","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A chart visualizing a metric."},{"type":"object","properties":{"type":{"type":"string","const":"big-number"},"properties":{"type":"object","properties":{"variant":{"type":"string","enum":["metrics","breakdown"],"description":"Layout variant: 'metrics' shows one tile per selected metric/slice; 'breakdown' shows one tile per value of a dimension for a single metric."},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID for this tile."},"sliceId":{"default":null,"description":"Optional slice/segment ID, or null for the whole metric.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["metricId","sliceId"],"additionalProperties":false,"description":"A metric (optionally narrowed to a slice) shown as one tile."},"description":"Metrics to show, one tile each. The breakdown variant uses exactly one entry."},"breakdownDimensionId":{"description":"Dimension ID to break the single metric down by. Required for the breakdown variant; unused otherwise.","type":"string"},"filters":{"description":"Record of dimensionId -> selected values. Values must be copied exactly as returned by the dimension lookup tool (case-sensitive). Never invent, infer, or modify values.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"compare":{"description":"Comparison shown as a delta on each tile: lag-1y compares to the same period last year; last-period compares to the previous period of equal length. last-period only works for standard periods — it is rejected for arbitrary custom date ranges, so use lag-1y there.","type":"string","enum":["lag-1y","last-period"]},"title":{"description":"Optional title displayed above the tiles.","type":"string"},"color":{"type":"string","enum":["gray","none","blue","green","red","yellow","purple","lime"],"description":"Tile background color. Defaults to 'gray' when omitted."},"breakdownSettings":{"type":"object","properties":{"sortBy":{"description":"How to sort breakdown tiles.","type":"string","enum":["value","name"]},"sortDirection":{"description":"Sort direction.","type":"string","enum":["asc","desc"]},"maxItems":{"description":"Maximum number of breakdown tiles to show (e.g. top 3).","type":"integer","exclusiveMinimum":0,"maximum":1000},"hideOther":{"description":"Whether to hide the aggregated 'Other' tile.","type":"boolean"},"show100PercentBars":{"description":"Not rendered by big numbers; carried for type parity.","type":"boolean"}},"additionalProperties":false},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["variant","metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"Headline KPI tiles — one large value per metric (variant 'metrics') or per dimension value (variant 'breakdown', exactly one metricSliceIds entry plus breakdownDimensionId set to a categorical dimension of that metric). Use for key-metrics-at-a-glance sections, typically before charts add detail."},{"type":"object","properties":{"type":{"type":"string","const":"table"},"properties":{"type":"object","properties":{"title":{"description":"Optional title shown above the table.","type":"string"},"transposed":{"type":"boolean"},"fullWidth":{"type":"boolean"},"metricSliceIds":{"minItems":1,"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"Metric ID — from ListMetrics / SearchMetrics."},"sliceId":{"description":"Optional slice/segment ID.","type":"string"},"props":{"description":"Optional per-metric column config (time comparisons).","type":"object","properties":{"compares":{"description":"Per-metric time comparisons shown as extra columns (e.g. lag-1y, year-over-year).","type":"object","propertyNames":{"type":"string","enum":["min","max","avg","avg-7d","avg-28d","lag-1y","year-over-year","lag-1y-same-weekday","year-over-year-same-weekday","last-period","x-over-x"]},"additionalProperties":{"type":"object","properties":{"displayVariants":{"default":["compare-values"],"type":"array","items":{"type":"string","enum":["compare-values","absolute-change-from-compare-values-to-actuals","relative-change-from-compare-values-to-actuals"]}}},"required":["displayVariants"],"additionalProperties":false}}},"additionalProperties":false}},"required":["metricId"],"additionalProperties":false},"description":"One or more metrics to show as columns."},"fromDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"toDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"breakdown":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"dimension"},"dimensionIdentifier":{"type":"string","description":"Dimension to break rows down by (one row per value) — the dimension's identifier (a readable column like 'country'), as returned by the dimension lookup tool, not the opaque dimension id. Must be a dimension of every chosen metric."},"settings":{"description":"Sort the rows and/or keep only the top N.","type":"object","properties":{"sortBy":{"type":"string","enum":["value","name"],"description":"Sort rows by value or name."},"sortDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction."},"maxItems":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Keep only the top N rows."},"hideOther":{"type":"boolean","description":"Hide the aggregated 'Other' row."}},"additionalProperties":false}},"required":["type","dimensionIdentifier"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"time"},"timeGrain":{"default":"auto","anyOf":[{"type":"string","enum":["daily","weekly","monthly","quarterly","yearly"]},{"type":"string","const":"auto"}],"description":"An explicit time grain, or 'auto' to let the system choose."}},"required":["type","timeGrain"],"additionalProperties":false}],"description":"How table rows are grouped: by a categorical dimension's values, or over time at a given grain. Defaults to time/auto when omitted."}},"required":["metricSliceIds","fromDate","toDate"],"additionalProperties":false}},"required":["type","properties"],"additionalProperties":false,"description":"A data table of one or more metrics as columns, with rows broken down by a categorical dimension or over time. Use when exact values matter or for side-by-side metric comparison; prefer chart blocks for trends."}]},"description":"The 2–4 content blocks rendered as equal-width columns, left to right."}},"required":["type","children"],"additionalProperties":false,"description":"A layout block that arranges 2–4 content blocks side by side as equal-width columns. Children must be content blocks (text, chart, big-number) — layout blocks cannot nest. Use for comparisons or related charts that read well next to each other."}]},"description":"Ordered list of blocks that make up the report body, in document order. Chart, table and big-number blocks reference metric `id`s from list metrics, search metrics, or get metric by `id`."}},"required":["title","blocks"],"additionalProperties":false}}}},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false,"title":"CreatedReport"}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"postV1Reports"},"get":{"description":"List reports in the workspace (metadata only, not content). Filter by creator, sharing, team, or metric; page with `limit` and `skip`. For keyword search use search reports; for full content use get report by `id`.","tags":["reports"],"x-steep":{"requiredScopes":["reports:read"],"requiredFeatureFlags":["reports-in-ai"],"exposeUnderMCP":true},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"description":"Maximum number of reports to return.","type":"integer","minimum":1,"maximum":100}},{"name":"skip","in":"query","required":false,"schema":{"default":0,"description":"Number of reports to skip, for paging.","type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"createdBy","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Only reports created by this user. Pass a workspace member's user `id` from list workspace members, or the literal `me` for the calling user (`me` requires a user token)."}},{"name":"sharedWith","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Only reports shared directly with this user, excluding reports they created. Pass a workspace member's user `id` from list workspace members, or the literal `me` for the calling user (`me` requires a user token). Cannot be combined with `teamId`."}},{"name":"teamId","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Only reports shared with this team. Cannot be combined with `sharedWith`."}},{"name":"metricId","in":"query","required":false,"schema":{"type":"string","minLength":1,"description":"Only reports whose blocks reference this metric (chart, table, big-number or map blocks). Pass a metric `id` from list metrics, search metrics, or get metric by `id`. Use to find which reports reference a given metric."}},{"name":"sort","in":"query","required":false,"schema":{"default":"updatedAt","description":"Field to sort by.","type":"string","enum":["createdAt","updatedAt"]}},{"name":"order","in":"query","required":false,"schema":{"default":"desc","description":"Sort direction.","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"When the report was created."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"When the report was last updated."},"author":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the user who created the report."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The display name of the user who created the report. Null if the user has no name set."}},"required":["id","name"],"additionalProperties":false,"title":"ReportAuthor"},{"type":"null"}],"description":"The user who created the report. Null if the creator is unknown."},"link":{"type":"string","description":"Link to the report in the Steep app."}},"required":["id","title","createdAt","updatedAt","author","link"],"additionalProperties":false,"title":"ReportListItem"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1Reports"}},"/v1/reports/search":{"get":{"description":"Search existing reports by title and content: report titles and block headings/titles (text blocks, and chart, table, big-number, and map block titles); body text is not searched. Multiple words are matched independently. Returns the most recently updated matching reports, each flagged by whether it matched on the title or on content. Prefer this first for broad or open-ended questions about how an area, topic, or the business is doing, such as 'how is retention trending?', 'what's the latest on churn?', or 'give me a read on sales this quarter'. Teams curate reports as the canonical, vetted answer to exactly these questions, so look for an existing report before assembling answers from individual metrics. Skip it for precise, computational asks that name a specific metric, value, breakdown, or chart, such as 'what was MRR last month?' or 'chart gross margin by month'; use the metric tools directly for those.","tags":["reports"],"x-steep":{"requiredScopes":["reports:read"],"requiredFeatureFlags":["reports-in-ai"],"exposeUnderMCP":true},"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search query of up to 5 words. Each word is matched independently: a report matches if any word appears in its title or content."}},{"name":"limit","in":"query","required":false,"schema":{"default":10,"description":"Maximum number of hits to return.","type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"title":{"type":"string"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"link":{"type":"string","description":"Link to the report in the Steep app."},"matchedOn":{"type":"string","enum":["title","content"],"description":"Why the report matched the keyword: `title` if it matched the report title, `content` if it matched block content (a text-block heading or a chart/table/big-number/map block title)."}},"required":["id","title","updatedAt","link","matchedOn"],"additionalProperties":false,"title":"Report"}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1ReportsSearch"}},"/v1/reports/{id}":{"get":{"description":"Read a report's full contents by `id`: title, each text block's heading and body, and the titles of chart/table/big-number/map blocks, in document order. Does not run metric queries.","tags":["reports"],"x-steep":{"requiredScopes":["reports:read"],"requiredFeatureFlags":["reports-in-ai"],"exposeUnderMCP":true},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"description":"The `id` of the report."}}],"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"When the report was created."},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$","description":"When the report was last updated."},"author":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the user who created the report."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The display name of the user who created the report. Null if the user has no name set."}},"required":["id","name"],"additionalProperties":false,"title":"ReportAuthor"},{"type":"null"}],"description":"The user who created the report. Null if the creator is unknown."},"link":{"type":"string","description":"Link to the report in the Steep app."},"blocks":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"text"},"heading":{"type":"string"},"headingSize":{"type":"string","enum":["large","small"]},"body":{"type":"string"}},"required":["id","type","heading","headingSize","body"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["chart","table","big-number","map"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"metrics":{"type":"array","items":{"type":"object","properties":{"metricId":{"type":"string","description":"The metric this series visualizes. Use query metric to fetch values, or get metric by `id` for its definition."},"sliceId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The slice/segment the metric is narrowed to, or null for the whole metric."}},"required":["metricId","sliceId"],"additionalProperties":false,"title":"ReportMetricRef"},"description":"The metrics visualized in this block, in display order. Empty for map blocks."},"timeFilter":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Relative time-window token (e.g. \"1w\", \"1y\"), or \"custom\" for an explicit fromDate/toDate range. Null if the block sets no time window."},"fromDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Start of the block's time window as an ISO 8601 string, when set."},"toDate":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"End of the block's time window as an ISO 8601 string, when set."}},"required":["id","type","title","metrics","timeFilter","fromDate","toDate"],"additionalProperties":false}]}}},"required":["id","title","createdAt","updatedAt","author","link","blocks"],"additionalProperties":false,"title":"ReportContent"}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1ReportsById"}},"/v1/workspace/members":{"get":{"description":"List members for your workspace.","tags":["workspace"],"x-steep":{"requiredScopes":["workspace-members:read"],"exposeUnderMCP":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"User `id` for this member. This matches `id`s returned in `metric.owners`."},"workspaceMemberId":{"type":"string","description":"Workspace member record `id`."},"name":{"type":"string"},"email":{"type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"type":"string"},"loginMethod":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","workspaceMemberId","name","email","image","role","loginMethod","createdAt","updatedAt"],"additionalProperties":false,"title":"Member"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1WorkspaceMembers"}},"/v1/workspace/teams":{"get":{"description":"List teams for your workspace.","tags":["workspace"],"x-steep":{"requiredScopes":["teams:read"],"exposeUnderMCP":true},"responses":{"200":{"description":"Response for status 200","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"skip":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique resource ID (opaque)."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"color":{"type":"string"},"isPrivate":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"User `id` for this member. This matches `id`s returned in `metric.owners`."},"workspaceMemberId":{"type":"string","description":"Workspace member record `id`."},"name":{"type":"string"},"email":{"type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}]},"loginMethod":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","workspaceMemberId","name","email","image","loginMethod","createdAt","updatedAt"],"additionalProperties":false}}},"required":["id","name","description","color","isPrivate","createdAt","updatedAt","members"],"additionalProperties":false,"title":"Team"}}},"required":["total","limit","skip","data"],"additionalProperties":false}}}},"401":{"description":"Response for status 401","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"Response for status 403","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"422":{"description":"Response for status 422","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"path":{"type":"string"}},"required":["message"],"additionalProperties":false}}},"required":["message","validationErrors"],"additionalProperties":false}}}},"429":{"description":"Response for status 429","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"Response for status 500","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}},"operationId":"getV1WorkspaceTeams"}}},"components":{"schemas":{}}}