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.

feat(flags): tell PostHog AI how to read flag calls kept in flag_evaluations (#127894)

Phil Haack2133ba3ec21c
diff --git a/ee/hogai/tools/execute_sql/prompts.py b/ee/hogai/tools/execute_sql/prompts.py
index 9eeae1150382..1d47fda8aa0e 100644
--- a/ee/hogai/tools/execute_sql/prompts.py
+++ b/ee/hogai/tools/execute_sql/prompts.py
@@ -43,6 +43,14 @@ Metadata (token counts, costs, model, $ai_trace_id, latency, error flags) stays
- Single trace: `SELECT input, output_choices FROM posthog.ai_events WHERE trace_id = '<id>' ORDER BY timestamp`
- Batch: filter the timestamp-indexed `events` table for trace IDs first, then fetch content from `posthog.ai_events` anchored on `trace_id`.
+# Feature flag calls
+`$feature_flag_called` records a flag evaluation. `$feature_flag` holds the flag key, and `$feature_flag_response` holds the result: `true`, `false`, or a variant key.
+Some organizations keep these calls only in `posthog.flag_evaluations`, for 90 days, and no longer in `events`.
+- Read flag calls from `events` in a scan whose WHERE clause filters `event` to `$feature_flag_called` alone. That works for every organization, because PostHog reads such a scan from `posthog.flag_evaluations` when the organization keeps its calls there.
+- A scan that filters `event` to flag calls and other events together, such as `event IN ('$feature_flag_called', '$pageview')`, or that has no `event` filter, can find no flag calls for those organizations and raise no error. Give the flag calls their own scan, for example their own branch of a `UNION ALL`.
+- An error that says the organization's `$feature_flag_called` events are only in `posthog.flag_evaluations` means that table exists. Select named columns instead of `*`, or query `posthog.flag_evaluations` directly. Its `flag_key` and `response` columns hold the flag key and the result.
+- Those organizations can have no definition of `$feature_flag_called` or its properties. A missing definition is not evidence that nothing calls a flag. Count the calls with SQL.
+
# Linked tables
`virtual_table` and `lazy_table` fields are connections to linked tables, e.g. the virtual table field `person` allows accessing person properties like so: `person.properties.foo`.
diff --git a/products/experiments/skills/diagnosing-experiment-health/references/empty-experiment.md b/products/experiments/skills/diagnosing-experiment-health/references/empty-experiment.md
index f9e4831a7c09..814bfd23f8ef 100644
--- a/products/experiments/skills/diagnosing-experiment-health/references/empty-experiment.md
+++ b/products/experiments/skills/diagnosing-experiment-health/references/empty-experiment.md
@@ -428,7 +428,9 @@ status from Step 1:
- `stopped` — the results end at the end date.
Then check where the project keeps its flag calls: `project-get` returns `flag_evaluations_mode`.
-At 2, `$feature_flag_called` no longer arrives in `events` for the projects that setting covers, and an experiment that counts that event gains no exposures, without a warning.
+At 2, `$feature_flag_called` no longer arrives in `events` for the projects that setting covers.
+The default exposure keeps counting from the `$experiment_exposure` copies ("Which event, which property" in `diagnostic-snapshot.md`).
+An exposure or activation config that is an action with a `$feature_flag_called` step can stop gaining exposures, without a warning.
That is no fault of the SDK or of the application: say so, and point the user to PostHog support.
Then read the flag's change history, before any conclusion about the application:
diff --git a/products/posthog_ai/skills/querying-posthog-data/SKILL.md b/products/posthog_ai/skills/querying-posthog-data/SKILL.md
index 67b3329d7d16..21b60ab1539a 100644
--- a/products/posthog_ai/skills/querying-posthog-data/SKILL.md
+++ b/products/posthog_ai/skills/querying-posthog-data/SKILL.md
@@ -124,7 +124,7 @@ Every column table below is generated from the live HogQL catalog, so it lists e
- [Data Warehouse](./references/models-data-warehouse.md)
- [Data Modeling Endpoints](./references/models-endpoints.md)
- [Error Tracking](./references/models-error-tracking.md)
-- [Flags & Experiments](./references/models-flags-experiments.md)
+- [Flags, flag calls (`$feature_flag_called`, `posthog.flag_evaluations`) & Experiments](./references/models-flags-experiments.md)
- [Heatmaps (`heatmaps` data + `system.heatmaps_saved`)](./references/models-heatmaps.md)
- [Hog Flows](./references/models-hog-flows.md)
- [Hog Functions](./references/models-hog-functions.md)
diff --git a/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2 b/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2
index 6297db8e3365..f1ab35d343e5 100644
--- a/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2
+++ b/products/posthog_ai/skills/querying-posthog-data/references/models-flags-experiments.md.j2
@@ -48,6 +48,48 @@ These are the only columns exposed via HogQL — the full flag model (e.g. `acti
---
+## Flag calls (`$feature_flag_called`)
+
+An SDK sends a `$feature_flag_called` event when code evaluates a flag.
+Its `$feature_flag` property holds the flag key, and `$feature_flag_response` holds the result: `true`, `false`, or a variant key.
+
+PostHog is moving these calls from `events` to `posthog.flag_evaluations`, one organization at a time.
+`project-get` returns the organization's `flag_evaluations_mode`:
+
+Mode | Where the flag calls are | `posthog.flag_evaluations`
+--- | --- | ---
+0 | `events` | Unknown table
+1 | `events` and `posthog.flag_evaluations` | Queryable
+2 | `posthog.flag_evaluations` only, for 90 days | Queryable
+
+### Query flag calls from `events` in a scan of their own
+
+Filter `event` to `$feature_flag_called` alone, as in `FROM events WHERE event = '$feature_flag_called'`.
+That query works in every mode, because PostHog reads such a scan from `posthog.flag_evaluations` when the organization keeps its calls there.
+On mode 2 it returns at most the last 90 days.
+
+On mode 2, these shapes can go wrong:
+
+- A scan that filters `event` to flag calls and other events together, such as `event IN ('$feature_flag_called', '$pageview')`, can read only `events` and return no flag calls, with no error.
+ A scan with no `event` filter, such as a count of every event, can leave the flag calls out the same way.
+ Give the flag calls their own scan: a separate query, or their own branch of a `UNION ALL`.
+- `SELECT *` and `SAMPLE` fail with an error that says the calls are only in `posthog.flag_evaluations`.
+ Select named columns, or query `posthog.flag_evaluations` directly.
+- The project can have no event or property definitions for `$feature_flag_called`, so `read-data-schema` can list neither the event nor its properties.
+ A missing definition is not evidence that nothing calls a flag. Count the calls with SQL.
+
+### `posthog.flag_evaluations`
+
+One row per flag call. Query it directly only on modes 1 and 2.
+Filter on `flag_key` rather than `properties.$feature_flag`: `flag_key` is in the table's sort key.
+
+{{ schema_columns('posthog.flag_evaluations') }}
+
+Never join this table to another one on `person_id`, because the query fails.
+Join on `distinct_id`, or filter with `person_id IN (SELECT person_id FROM posthog.flag_evaluations WHERE ...)`.
+
+---
+
## Experiment (`system.experiments`)
Experiments are A/B tests that compare variants against a control group.
diff --git a/products/posthog_ai/skills/querying-posthog-data/references/taxonomy-skipped-events.md b/products/posthog_ai/skills/querying-posthog-data/references/taxonomy-skipped-events.md
index 89c1bb7a5a40..c8c4de14011c 100644
--- a/products/posthog_ai/skills/querying-posthog-data/references/taxonomy-skipped-events.md
+++ b/products/posthog_ai/skills/querying-posthog-data/references/taxonomy-skipped-events.md
@@ -19,3 +19,5 @@ Event | Reason
`$groupidentify` | Group identification event
These events are filtered at the SQL level using a `NOT IN` clause, so they don't consume pagination slots.
+
+To answer a question about flag calls, query `$feature_flag_called` with SQL as [Flags & Experiments](./models-flags-experiments.md) describes.
diff --git a/products/signals/skills/signals-scout-feature-flags/SKILL.md b/products/signals/skills/signals-scout-feature-flags/SKILL.md
index 305c8d8b53a1..14518920508a 100644
--- a/products/signals/skills/signals-scout-feature-flags/SKILL.md
+++ b/products/signals/skills/signals-scout-feature-flags/SKILL.md
@@ -321,9 +321,9 @@ Direct calls (read-only):
- `feature-flags-activity-retrieve` — one flag's edit history with diffs; how you date edits against traffic shifts.
- `feature-flags-dependent-flags-retrieve` — flags whose conditions reference this one; the per-flag cleanup-safety check.
- `advanced-activity-logs-list` (`scopes: ["FeatureFlag"]`) — project-wide flag change timeline, including deletions that `feature-flags-activity-retrieve` can't reach anymore.
-- `execute-sql` against `events` — the traffic side. Properties on `$feature_flag_called`: `$feature_flag` (key), `$feature_flag_response` (`true`/`false`/variant key).
+- `execute-sql` against `events` — the traffic side. Properties on `$feature_flag_called`: `$feature_flag` (key), `$feature_flag_response` (`true`/`false`/variant key). Keep `event = '$feature_flag_called'` as the only event filter of each scan, as the queries above do. PostHog then reads `posthog.flag_evaluations` for an organization that keeps its flag calls only there. A scan that also matches other events can find none of those calls.
- `execute-sql` against `system.feature_flags` — the bulk roster side (`id`, `key`, `name`, `filters`, `rollout_percentage`, `deleted`; no `active` column). Powers the ghost anti-join and any roster-wide aggregation without pagination.
-- `read-data-schema` — confirm `$feature_flag_called` exists and check property shape before aggregating.
+- `read-data-schema` — check property shape before aggregating. It can list no `$feature_flag_called` definitions for an organization that keeps flag calls only in `posthog.flag_evaluations`, so confirm the stream with the count query in [Quick close-out](#quick-close-out-are-flags-even-in-use), not here.
Stale-flag health issues (the deterministic classifier you read, never re-run):