Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(app-metrics): return requested metrics with no rows as zeros (#127144)

Michael Reichenbachbaebb723020c
diff --git a/posthog/api/app_metrics2.py b/posthog/api/app_metrics2.py
index eed004bb2fe5..ebb06e0274c4 100644
--- a/posthog/api/app_metrics2.py
+++ b/posthog/api/app_metrics2.py
@@ -51,6 +51,30 @@ class AppMetricsTotalsResponseSerializer(DataclassSerializer):
dataclass = AppMetricsTotalsResponse
+MAX_REQUESTED_BREAKDOWN_VALUES = 50
+
+MAX_TREND_BUCKETS = 100_000
+
+MAX_ZERO_FILLED_CELLS = 1_000_000
+
+TREND_INTERVAL_STEPS: dict[str, timedelta] = {
+ "hour": timedelta(hours=1),
+ "day": timedelta(days=1),
+ "week": timedelta(weeks=1),
+}
+
+
+def _split_requested_values(value: str) -> list[str]:
+ values = list(dict.fromkeys(part.strip() for part in value.split(",") if part.strip()))
+ if not values:
+ raise serializers.ValidationError("Enter at least one value. Separate values with commas.")
+ if len(values) > MAX_REQUESTED_BREAKDOWN_VALUES:
+ raise serializers.ValidationError(
+ f"Request at most {MAX_REQUESTED_BREAKDOWN_VALUES} distinct values, got {len(values)}."
+ )
+ return values
+
+
class AppMetricsRequestSerializer(serializers.Serializer):
after = serializers.CharField(
required=False,
@@ -73,11 +97,11 @@ class AppMetricsRequestSerializer(serializers.Serializer):
)
name = serializers.CharField(
required=False,
- help_text="Comma-separated metric names to filter by.",
+ help_text="Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.",
)
kind = serializers.CharField(
required=False,
- help_text="Comma-separated metric kinds to filter by, e.g. 'success,failure'.",
+ help_text="Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.",
)
breakdown_by = serializers.ChoiceField(
choices=["name", "kind"],
@@ -86,6 +110,25 @@ class AppMetricsRequestSerializer(serializers.Serializer):
help_text="Group the series by metric 'name' or 'kind'. Defaults to 'kind'.",
)
+ def validate_name(self, value: str) -> list[str]:
+ return _split_requested_values(value)
+
+ def validate_kind(self, value: str) -> list[str]:
+ return _split_requested_values(value)
+
+
+def _requested_breakdown_values(breakdown_by: str, name: list[str], kind: list[str]) -> list[str]:
+ return name if breakdown_by == "name" else kind
+
+
+def _trend_range_start(after: datetime, interval: str) -> datetime:
+ if interval == "hour":
+ return after.replace(minute=0, second=0, microsecond=0)
+ start = after.replace(hour=0, minute=0, second=0, microsecond=0)
+ if interval == "week":
+ start -= timedelta(days=start.weekday())
+ return start
+
def fetch_app_metrics_trends(
team_id: int,
@@ -104,6 +147,23 @@ def fetch_app_metrics_trends(
name = name or []
kind = kind or []
+ range_start = _trend_range_start(after, interval)
+ step = TREND_INTERVAL_STEPS[interval]
+ bucket_count = (before - range_start) // step + 1 if before >= range_start else 0
+ if bucket_count > MAX_TREND_BUCKETS:
+ raise ValidationError(
+ f"This range has {bucket_count:,} {interval} buckets, more than the limit of {MAX_TREND_BUCKETS:,}. "
+ "Use a shorter range or a larger interval."
+ )
+
+ requested_breakdown_values = _requested_breakdown_values(breakdown_by, name, kind)
+ if len(requested_breakdown_values) * bucket_count > MAX_ZERO_FILLED_CELLS:
+ raise ValidationError(
+ f"This request asks for {len(requested_breakdown_values)} series over {bucket_count:,} {interval} buckets, "
+ f"more than the limit of {MAX_ZERO_FILLED_CELLS:,} values. "
+ "Request fewer names or kinds, a shorter range, or a larger interval."
+ )
+
clickhouse_kwargs: dict[str, Any] = {}
# The bucket alias must not be `timestamp`. ClickHouse resolves SELECT aliases inside WHERE, so the
@@ -145,32 +205,13 @@ def fetch_app_metrics_trends(
raise ValueError("Unexpected results from ClickHouse")
# We create the x values based on the date range and interval
- labels: list[str] = []
label_format = "%Y-%m-%dT%H:%M" if interval == "hour" else "%Y-%m-%d"
-
- range_date = after
- # Normalize the start of the range to the start of the interval
- if interval == "hour":
- range_date = range_date.replace(minute=0, second=0, microsecond=0)
- elif interval == "day":
- range_date = range_date.replace(hour=0, minute=0, second=0, microsecond=0)
- elif interval == "week":
- range_date = range_date.replace(hour=0, minute=0, second=0, microsecond=0)
- range_date -= timedelta(days=range_date.weekday())
-
- while range_date <= before:
- labels.append(range_date.strftime(label_format))
- if interval == "hour":
- range_date += timedelta(hours=1)
- elif interval == "day":
- range_date += timedelta(days=1)
- elif interval == "week":
- range_date += timedelta(weeks=1)
+ labels = [(range_start + step * i).strftime(label_format) for i in range(bucket_count)]
response = AppMetricsResponse(labels=[], series=[])
data_by_breakdown: dict[str, dict[str, int]] = {}
- breakdown_names = {row[1] for row in results}
+ breakdown_names = dict.fromkeys([*requested_breakdown_values, *(row[1] for row in results)])
for result in results:
timestamp, breakdown, count = result
@@ -248,7 +289,9 @@ def fetch_app_metric_totals(
if not isinstance(results, list):
raise ValueError("Unexpected results from ClickHouse")
- totals = {row[0]: row[1] for row in results}
+ totals = dict.fromkeys(_requested_breakdown_values(breakdown_by, name, kind), 0) | {
+ row[0]: row[1] for row in results
+ }
return AppMetricsTotalsResponse(totals=totals)
@@ -507,8 +550,8 @@ class AppMetricsMixin(viewsets.GenericViewSet):
after=after_date,
before=before_date,
breakdown_by=params.get("breakdown_by"),
- name=params["name"].split(",") if params.get("name") else None,
- kind=params["kind"].split(",") if params.get("kind") else None,
+ name=params.get("name") or None,
+ kind=params.get("kind") or None,
)
serializer = AppMetricResponseSerializer(instance=data)
@@ -549,8 +592,8 @@ class AppMetricsMixin(viewsets.GenericViewSet):
after=after_date,
before=before_date,
breakdown_by=params.get("breakdown_by"),
- name=params["name"].split(",") if params.get("name") else None,
- kind=params["kind"].split(",") if params.get("kind") else None,
+ name=params.get("name") or None,
+ kind=params.get("kind") or None,
)
serializer = AppMetricsTotalsResponseSerializer(instance=data)
diff --git a/posthog/api/event_filter_config.py b/posthog/api/event_filter_config.py
index 7dcece6565b3..94d9ecaa43d4 100644
--- a/posthog/api/event_filter_config.py
+++ b/posthog/api/event_filter_config.py
@@ -137,8 +137,8 @@ class EventFilterConfigViewSet(TeamAndOrgViewSetMixin, viewsets.GenericViewSet):
"before": before_date,
"interval": params.get("interval", "day"),
"breakdown_by": params.get("breakdown_by"),
- "name": params["name"].split(",") if params.get("name") else None,
- "kind": params["kind"].split(",") if params.get("kind") else None,
+ "name": params.get("name") or None,
+ "kind": params.get("kind") or None,
}
@extend_schema(responses={200: AppMetricResponseSerializer})
diff --git a/posthog/api/test/test_app_metrics2.py b/posthog/api/test/test_app_metrics2.py
index 786bb39b4947..9cd091cb937b 100644
--- a/posthog/api/test/test_app_metrics2.py
+++ b/posthog/api/test/test_app_metrics2.py
@@ -2,13 +2,26 @@ from datetime import UTC, datetime, timedelta
from typing import Any
from zoneinfo import ZoneInfo
-from posthog.test.base import BaseTest, ClickhouseTestMixin
+from posthog.test.base import APIBaseTest, BaseTest, ClickhouseTestMixin
+
+from django.test import SimpleTestCase
from parameterized import parameterized
+from rest_framework import status
-from posthog.api.app_metrics2 import fetch_app_metric_totals, fetch_app_metrics_trends
+from posthog.api.app_metrics2 import (
+ MAX_TREND_BUCKETS,
+ MAX_ZERO_FILLED_CELLS,
+ AppMetricsRequestSerializer,
+ fetch_app_metric_totals,
+ fetch_app_metrics_trends,
+)
from posthog.test.fixtures import create_app_metric2
+from products.cdp.backend.models.hog_functions.hog_function import HogFunction
+
+DISTINCT_51 = ",".join(f"metric_{i}" for i in range(51))
+
class TestAppMetrics2Timezone(ClickhouseTestMixin, BaseTest):
def _seed(self, when_utc: datetime, app_source_id: str = "fn-1") -> None:
@@ -37,6 +50,34 @@ class TestAppMetrics2Timezone(ClickhouseTestMixin, BaseTest):
assert result.totals == {"success": 1}
+ @parameterized.expand(
+ [
+ ("name", {"name": ["succeeded", "skipped"]}, "skipped"),
+ ("kind", {"kind": ["success", "failure"]}, "failure"),
+ ]
+ )
+ def test_requested_breakdown_values_without_rows_read_as_zero(
+ self, breakdown_by: str, filters: dict[str, Any], missing: str
+ ) -> None:
+ after = datetime(2026, 6, 8, 0, 0, tzinfo=UTC)
+ before = datetime(2026, 6, 9, 23, 0, tzinfo=UTC)
+ self._seed(after + timedelta(hours=12))
+ query = {
+ "team_id": self.team.pk,
+ "app_source": "hog_function",
+ "app_source_id": "fn-1",
+ "after": after,
+ "before": before,
+ "breakdown_by": breakdown_by,
+ **filters,
+ }
+
+ trends = fetch_app_metrics_trends(**query)
+ totals = fetch_app_metric_totals(**query)
+
+ assert {series.name: series.values for series in trends.series}[missing] == [0, 0]
+ assert totals.totals[missing] == 0
+
@parameterized.expand(
[
("America/Los_Angeles",), # -07:00 (PDT in June)
@@ -99,3 +140,69 @@ class TestAppMetrics2Timezone(ClickhouseTestMixin, BaseTest):
assert [(series.name, series.values) for series in trends.series] == [("success", expected)]
assert totals.totals == {"success": sum(expected)}
+
+
+class TestAppMetricsRequestSerializer(SimpleTestCase):
+ @parameterized.expand(
+ [
+ ("name_at_limit", "name", ",".join(f"m{i}" for i in range(50)), [f"m{i}" for i in range(50)]),
+ ("kind_duplicates_and_blanks", "kind", " success, failure,,success ," * 40, ["success", "failure"]),
+ ("name_over_limit", "name", DISTINCT_51, None),
+ ("kind_over_limit", "kind", DISTINCT_51, None),
+ ("name_only_blanks", "name", ", ,,", None),
+ ]
+ )
+ def test_requested_values_are_deduped_and_capped(
+ self, _name: str, field: str, raw: str, expected: list[str] | None
+ ) -> None:
+ serializer = AppMetricsRequestSerializer(data={field: raw})
+
+ if expected is None:
+ assert not serializer.is_valid()
+ assert field in serializer.errors
+ else:
+ assert serializer.is_valid(), serializer.errors
+ assert serializer.validated_data[field] == expected
+
+
+class TestAppMetricsEndpointLimits(APIBaseTest):
+ @parameterized.expand([("metrics/",), ("metrics/totals/",)])
+ def test_too_many_requested_names_is_a_400(self, path: str) -> None:
+ hog_function = HogFunction.objects.create(team=self.team, name="destination", type="destination", hog="")
+
+ response = self.client.get(
+ f"/api/projects/{self.team.id}/hog_functions/{hog_function.id}/{path}",
+ {"name": DISTINCT_51, "breakdown_by": "name", "interval": "hour"},
+ )
+
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert response.json()["attr"] == "name"
+
+ @parameterized.expand(
+ [
+ ("buckets_at_limit", 0, MAX_TREND_BUCKETS, None),
+ ("buckets_over_limit", 0, MAX_TREND_BUCKETS + 1, "Use a shorter range or a larger interval."),
+ ("cells_at_limit", 50, MAX_ZERO_FILLED_CELLS // 50, None),
+ ("cells_over_limit", 50, MAX_ZERO_FILLED_CELLS // 50 + 1, "Request fewer names or kinds"),
+ ]
+ )
+ def test_trend_size_is_capped(self, _name: str, name_count: int, bucket_count: int, error: str | None) -> None:
+ hog_function = HogFunction.objects.create(team=self.team, name="destination", type="destination", hog="")
+ after = datetime(2020, 1, 1, tzinfo=UTC)
+ params = {
+ "after": after.isoformat(),
+ "before": (after + timedelta(hours=bucket_count - 1)).isoformat(),
+ "interval": "hour",
+ }
+ if name_count:
+ params |= {"name": ",".join(f"m{i}" for i in range(name_count)), "breakdown_by": "name"}
+
+ response = self.client.get(f"/api/projects/{self.team.id}/hog_functions/{hog_function.id}/metrics/", params)
+
+ if error is None:
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert len(response.json()["labels"]) == bucket_count
+ assert len(response.json()["series"]) == name_count
+ else:
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert error in response.json()["detail"]
diff --git a/posthog/api/test/test_event_filter_config.py b/posthog/api/test/test_event_filter_config.py
index f5d4f257d42d..2cbdea1297fb 100644
--- a/posthog/api/test/test_event_filter_config.py
+++ b/posthog/api/test/test_event_filter_config.py
@@ -234,11 +234,12 @@ class TestEventFilterConfigAPI(APIBaseTest):
mock_fetch.return_value = AppMetricsResponse(labels=["2026-04-01"], series=[])
self._seed_config()
- response = self.client.get(self._url() + "metrics/")
+ response = self.client.get(self._url() + "metrics/", {"kind": "success, failure,success"})
self.assertEqual(response.status_code, status.HTTP_200_OK)
mock_fetch.assert_called_once()
self.assertEqual(mock_fetch.call_args.kwargs["app_source"], "event_filter")
+ self.assertEqual(mock_fetch.call_args.kwargs["kind"], ["success", "failure"])
@patch("posthog.api.event_filter_config.fetch_app_metric_totals")
def test_metrics_totals_calls_clickhouse_when_config_exists(self, mock_fetch):
diff --git a/products/cdp/frontend/generated/api.schemas.ts b/products/cdp/frontend/generated/api.schemas.ts
index d747af8fa145..d62cd356b4d2 100644
--- a/products/cdp/frontend/generated/api.schemas.ts
+++ b/products/cdp/frontend/generated/api.schemas.ts
@@ -955,12 +955,12 @@ export type HogFunctionsMetricsRetrieveParams = {
*/
interval?: HogFunctionsMetricsRetrieveInterval
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string
@@ -1017,12 +1017,12 @@ export type HogFunctionsMetricsTotalsRetrieveParams = {
*/
interval?: HogFunctionsMetricsTotalsRetrieveInterval
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string
diff --git a/products/signals/skills/signals-scout-workflows/SKILL.md b/products/signals/skills/signals-scout-workflows/SKILL.md
index 7df258fa41da..bcdefd214ccd 100644
--- a/products/signals/skills/signals-scout-workflows/SKILL.md
+++ b/products/signals/skills/signals-scout-workflows/SKILL.md
@@ -64,7 +64,8 @@ Never suggest against a workflow that is not on this list — the API refuses it
### Read the numbers
-Per workflow, `workflows-version-stats` with `version=<the workflow's current version>`, `breakdown_by=name`, and `instance_id` set to the email step you are reading.
+Per workflow, `workflows-version-stats` with `version=<the workflow's current version>`, `breakdown_by=name`, `name=email_sent,email_untracked,email_opened,email_link_clicked,email_bounced,email_blocked`, and `instance_id` set to the email step you are reading.
+Every metric you name comes back, with zeros where the step recorded none, so a step with tracking on for every send shows `email_untracked` at 0.
Set `after` and `before` to the UTC start and end of the closed days you read, such as `after=2026-10-08T00:00:00Z` and `before=2026-10-15T00:00:00Z`, and sum the days from `after` up to the day before `before`.
A relative `after=-7d` starts at this hour seven days ago in the project's timezone, so its first day is partial and your numbers will not match the window you file.
`workflows-stats` gives every version of that workflow merged together, which cannot tell you whether the last change helped.
diff --git a/products/workflows/backend/presentation/views/hog_flow.py b/products/workflows/backend/presentation/views/hog_flow.py
index 5c9af73266e6..9cb4976ff9f2 100644
--- a/products/workflows/backend/presentation/views/hog_flow.py
+++ b/products/workflows/backend/presentation/views/hog_flow.py
@@ -5128,8 +5128,8 @@ class HogFlowViewSet(
after=after_date,
before=before_date,
breakdown_by=params.get("breakdown_by"),
- name=params["name"].split(",") if params.get("name") else None,
- kind=params["kind"].split(",") if params.get("kind") else None,
+ name=params.get("name") or None,
+ kind=params.get("kind") or None,
)
return Response(AppMetricResponseSerializer(instance=data).data)
diff --git a/products/workflows/backend/tests/api/test_hog_flow.py b/products/workflows/backend/tests/api/test_hog_flow.py
index 506a53e2a039..0bac06521953 100644
--- a/products/workflows/backend/tests/api/test_hog_flow.py
+++ b/products/workflows/backend/tests/api/test_hog_flow.py
@@ -6812,12 +6812,15 @@ class TestHogFlowVersionedMetrics(ClickhouseTestMixin, APIBaseTest):
self._seed("hog_flow", str(self.flow.id), succeeded=7)
base = f"/api/projects/{self.team.id}/hog_flows/{self.flow.id}"
- version_one = self.client.get(f"{base}/metrics/version?version=1")
+ version_one = self.client.get(f"{base}/metrics/version?version=1&breakdown_by=name&name=succeeded,skipped")
version_two = self.client.get(f"{base}/metrics/version?version=2")
whole = self.client.get(f"{base}/metrics")
assert version_one.status_code == 200, version_one.json()
- assert self._succeeded(version_one) == 3
+ assert {series["name"]: sum(series["values"]) for series in version_one.json()["series"]} == {
+ "succeeded": 3,
+ "skipped": 0,
+ }
assert self._succeeded(version_two) == 5
# The unversioned read keys batch runs on the run, so it is its own series rather than a sum.
assert self._succeeded(whole) == 7
diff --git a/products/workflows/frontend/generated/api.schemas.ts b/products/workflows/frontend/generated/api.schemas.ts
index 9c88c2f5c954..89ceffdc23c6 100644
--- a/products/workflows/frontend/generated/api.schemas.ts
+++ b/products/workflows/frontend/generated/api.schemas.ts
@@ -3389,12 +3389,12 @@ export type HogFlowsMetricsRetrieveParams = {
*/
interval?: HogFlowsMetricsRetrieveInterval
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string
@@ -3451,12 +3451,12 @@ export type HogFlowsMetricsTotalsRetrieveParams = {
*/
interval?: HogFlowsMetricsTotalsRetrieveInterval
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string
@@ -3513,12 +3513,12 @@ export type HogFlowsMetricsVersionRetrieveParams = {
*/
interval?: HogFlowsMetricsVersionRetrieveInterval
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string
diff --git a/products/workflows/mcp/tools.yaml b/products/workflows/mcp/tools.yaml
index 889c65ad255c..4901622bf48e 100644
--- a/products/workflows/mcp/tools.yaml
+++ b/products/workflows/mcp/tools.yaml
@@ -664,8 +664,9 @@ tools:
at-a-glance view across ALL workflows, call workflows-global-stats first, then drill in here. Supports
breakdown by metric kind (success/failure) or name, and time range filtering. For email engagement, read
email_opened and email_link_clicked against (email_sent - email_untracked): email_untracked counts sends
- with open/click tracking off, which can never register an open or a click. This reads the workflow's whole
- history; for one published version, call workflows-version-stats.
+ with open/click tracking off, which can never register an open or a click. Set breakdown_by=name and name
+ the metrics you read in `name`: each named metric is returned, as zeros when it recorded nothing. This reads
+ the workflow's whole history; for one published version, call workflows-version-stats.
workflows-suggest:
operation: hog_flows_proposals_create
enabled: true
@@ -773,4 +774,5 @@ tools:
how you tell whether a change helped: compare the version before it with the version after it. The
unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it
is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step
- you are reading, or several steps share one denominator.
+ you are reading, or several steps share one denominator. Set breakdown_by=name and name the metrics you read
+ in `name`: each named metric is returned, as zeros when that version recorded nothing.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 84dda0cbeab1..cc2d7b0aed00 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -17390,7 +17390,7 @@
}
},
"workflows-stats": {
- "description": "Execution stats for a single workflow by ID: time-series success/failure counts over a configurable interval (hour, day, or week). Use to inspect one workflow's health — failure spikes and reliability trends. For an at-a-glance view across ALL workflows, call workflows-global-stats first, then drill in here. Supports breakdown by metric kind (success/failure) or name, and time range filtering. For email engagement, read email_opened and email_link_clicked against (email_sent - email_untracked): email_untracked counts sends with open/click tracking off, which can never register an open or a click. This reads the workflow's whole history; for one published version, call workflows-version-stats.",
+ "description": "Execution stats for a single workflow by ID: time-series success/failure counts over a configurable interval (hour, day, or week). Use to inspect one workflow's health — failure spikes and reliability trends. For an at-a-glance view across ALL workflows, call workflows-global-stats first, then drill in here. Supports breakdown by metric kind (success/failure) or name, and time range filtering. For email engagement, read email_opened and email_link_clicked against (email_sent - email_untracked): email_untracked counts sends with open/click tracking off, which can never register an open or a click. Set breakdown_by=name and name the metrics you read in `name`: each named metric is returned, as zeros when it recorded nothing. This reads the workflow's whole history; for one published version, call workflows-version-stats.",
"category": "Workflows",
"feature": "workflows",
"summary": "Get workflow stats",
@@ -17480,7 +17480,7 @@
}
},
"workflows-version-stats": {
- "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator.",
+ "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator. Set breakdown_by=name and name the metrics you read in `name`: each named metric is returned, as zeros when that version recorded nothing.",
"category": "Workflows",
"feature": "workflows",
"summary": "Get workflow stats for one version",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 16f6f73640ee..fc4e7fa9bb65 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -18235,7 +18235,7 @@
}
},
"workflows-stats": {
- "description": "Execution stats for a single workflow by ID: time-series success/failure counts over a configurable interval (hour, day, or week). Use to inspect one workflow's health — failure spikes and reliability trends. For an at-a-glance view across ALL workflows, call workflows-global-stats first, then drill in here. Supports breakdown by metric kind (success/failure) or name, and time range filtering. For email engagement, read email_opened and email_link_clicked against (email_sent - email_untracked): email_untracked counts sends with open/click tracking off, which can never register an open or a click. This reads the workflow's whole history; for one published version, call workflows-version-stats.",
+ "description": "Execution stats for a single workflow by ID: time-series success/failure counts over a configurable interval (hour, day, or week). Use to inspect one workflow's health — failure spikes and reliability trends. For an at-a-glance view across ALL workflows, call workflows-global-stats first, then drill in here. Supports breakdown by metric kind (success/failure) or name, and time range filtering. For email engagement, read email_opened and email_link_clicked against (email_sent - email_untracked): email_untracked counts sends with open/click tracking off, which can never register an open or a click. Set breakdown_by=name and name the metrics you read in `name`: each named metric is returned, as zeros when it recorded nothing. This reads the workflow's whole history; for one published version, call workflows-version-stats.",
"category": "Workflows",
"feature": "workflows",
"summary": "Get workflow stats",
@@ -18325,7 +18325,7 @@
}
},
"workflows-version-stats": {
- "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator.",
+ "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator. Set breakdown_by=name and name the metrics you read in `name`: each named metric is returned, as zeros when that version recorded nothing.",
"category": "Workflows",
"feature": "workflows",
"summary": "Get workflow stats for one version",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index d7c32bf479ea..4af0e2ebff6f 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -127205,12 +127205,12 @@ export namespace Schemas {
*/
interval?: HogFlowsMetricsRetrieveInterval;
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string;
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string;
@@ -127267,12 +127267,12 @@ export namespace Schemas {
*/
interval?: HogFlowsMetricsTotalsRetrieveInterval;
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string;
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string;
@@ -127329,12 +127329,12 @@ export namespace Schemas {
*/
interval?: HogFlowsMetricsVersionRetrieveInterval;
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string;
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string;
@@ -127544,12 +127544,12 @@ export namespace Schemas {
*/
interval?: HogFunctionsMetricsRetrieveInterval;
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string;
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string;
@@ -127606,12 +127606,12 @@ export namespace Schemas {
*/
interval?: HogFunctionsMetricsTotalsRetrieveInterval;
/**
- * Comma-separated metric kinds to filter by, e.g. 'success,failure'.
+ * Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.
* @minLength 1
*/
kind?: string;
/**
- * Comma-separated metric names to filter by.
+ * Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.
* @minLength 1
*/
name?: string;
diff --git a/services/mcp/src/generated/cdp_functions/api.ts b/services/mcp/src/generated/cdp_functions/api.ts
index a54de2575ecc..54f33f571ce7 100644
--- a/services/mcp/src/generated/cdp_functions/api.ts
+++ b/services/mcp/src/generated/cdp_functions/api.ts
@@ -1176,8 +1176,20 @@ export const HogFunctionsMetricsRetrieveQueryParams = () => zod.object({
.describe(
"Time bucket size for the series. One of: hour, day, week. Defaults to 'day'.\n\n\* `hour` - hour\n\* `day` - day\n\* `week` - week"
),
- kind: zod.string().min(1).optional().describe("Comma-separated metric kinds to filter by, e.g. 'success,failure'."),
- name: zod.string().min(1).optional().describe('Comma-separated metric names to filter by.'),
+ kind: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows."
+ ),
+ name: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ 'Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.'
+ ),
})
export const HogFunctionsPublishCreateParams = () => zod.object({
diff --git a/services/mcp/src/generated/workflows/api.ts b/services/mcp/src/generated/workflows/api.ts
index 8e3094ed28a5..b2439e01fdb4 100644
--- a/services/mcp/src/generated/workflows/api.ts
+++ b/services/mcp/src/generated/workflows/api.ts
@@ -1108,8 +1108,20 @@ export const HogFlowsMetricsRetrieveQueryParams = () => zod.object({
.describe(
"Time bucket size for the series. One of: hour, day, week. Defaults to 'day'.\n\n\* `hour` - hour\n\* `day` - day\n\* `week` - week"
),
- kind: zod.string().min(1).optional().describe("Comma-separated metric kinds to filter by, e.g. 'success,failure'."),
- name: zod.string().min(1).optional().describe('Comma-separated metric names to filter by.'),
+ kind: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows."
+ ),
+ name: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ 'Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.'
+ ),
})
/**
@@ -1154,8 +1166,20 @@ export const HogFlowsMetricsVersionRetrieveQueryParams = () => zod.object({
.describe(
"Time bucket size for the series. One of: hour, day, week. Defaults to 'day'.\n\n\* `hour` - hour\n\* `day` - day\n\* `week` - week"
),
- kind: zod.string().min(1).optional().describe("Comma-separated metric kinds to filter by, e.g. 'success,failure'."),
- name: zod.string().min(1).optional().describe('Comma-separated metric names to filter by.'),
+ kind: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows."
+ ),
+ name: zod
+ .string()
+ .min(1)
+ .optional()
+ .describe(
+ 'Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.'
+ ),
version: zod
.number()
.describe(
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/cdp-functions-metrics-retrieve.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/cdp-functions-metrics-retrieve.json
index c16b76b88548..8b2e08c1111e 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/cdp-functions-metrics-retrieve.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/cdp-functions-metrics-retrieve.json
@@ -34,12 +34,12 @@
"type": "string"
},
"kind": {
- "description": "Comma-separated metric kinds to filter by, e.g. 'success,failure'.",
+ "description": "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
},
"name": {
- "description": "Comma-separated metric names to filter by.",
+ "description": "Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-stats.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-stats.json
index dcfdc7ae07a5..8d3fa554a114 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-stats.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-stats.json
@@ -34,12 +34,12 @@
"type": "string"
},
"kind": {
- "description": "Comma-separated metric kinds to filter by, e.g. 'success,failure'.",
+ "description": "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
},
"name": {
- "description": "Comma-separated metric names to filter by.",
+ "description": "Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
}
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-version-stats.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-version-stats.json
index 7d7af1e8f106..0243e1862330 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-version-stats.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-version-stats.json
@@ -34,12 +34,12 @@
"type": "string"
},
"kind": {
- "description": "Comma-separated metric kinds to filter by, e.g. 'success,failure'.",
+ "description": "Comma-separated metric kinds to filter by, up to 50, e.g. 'success,failure'. With breakdown_by=kind, each named kind is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
},
"name": {
- "description": "Comma-separated metric names to filter by.",
+ "description": "Comma-separated metric names to filter by, up to 50. With breakdown_by=name, each named metric is returned, as zeros when it has no rows.",
"minLength": 1,
"type": "string"
},