Build audience segments from product usage and push to Loops

Build me a segment builder app that my growth and lifecycle marketers open to define an audience from real product behaviour in PostHog and push it into Loops themselves. Today that job needs an engineer to write API calls, so the whole app is designed for a marketer: nothing requires writing code, every write is previewed and confirmed first, and the app never assumes a push succeeded.

Screen one is the segment builder. It offers two ways to define an audience, side by side as tabs. Cohort mode: call PostHog List Cohorts to populate a picker of existing cohorts, and when one is selected call List Cohort Persons to resolve its members. Query mode: a visual criteria composer where the marketer stacks rules such as event name, how many times it happened, the time window, person property filters, and negative rules like did not do event X. Compile those rules into HogQL and run them with Execute HogQL Query. Show the generated HogQL in a collapsible panel underneath the composer so a curious marketer or a passing engineer can read exactly what will run, but never require anyone to edit it.

Both modes feed one live preview panel that is always visible: the matched person count in large type, and a sample table of up to 50 matched people showing email and the person properties used by the criteria. Re-resolve the preview whenever the criteria change, but debounce it and never fire on keystroke. PostHog limits HogQL queries to roughly 240 per minute with 3 concurrent queries and a 10 second execution ceiling, so serialize preview runs, cancel superseded ones, and show a clear message if a query times out or is rate limited rather than an empty state that looks like zero matches.

Screen two is the push panel, which is where this pays off. Call Loops List Mailing Lists to populate a mailing list picker and Loops List Contact Properties to populate a property editor where the marketer chooses which contact properties to set and what value each gets for this segment. Include an inline New property form that calls Loops Create Contact Property so a marketer can define a brand new property without leaving the app, then immediately use it. Offer two push modes. Mode one writes per person with Loops Update Contact, which is an upsert: send mailingLists as an object mapping mailing list ID to boolean where true subscribes and false unsubscribes, for example { "cm1234abcd": true }, plus arbitrary camelCase top level keys as custom properties whose values may be string, number, boolean, or ISO-8601 date. Mode two fires a sequence for the whole segment with Loops Send Event using an event name the marketer picks. Send a fresh UUID Idempotency-Key header per person per push so a retried batch does not double fire, and treat the 409 that comes back from reusing a key within 24 hours as already sent rather than a failure. Offer Loops Find Contact as a per-row inspect action so a marketer can check what one person looks like in Loops before committing.

Safety is the point, because this is used by marketers rather than engineers. Dry run is a toggle that defaults to on, and a dry run resolves the segment and renders the exact payload that would be written for a sample of people while writing absolutely nothing. Turning dry run off and pressing push must open a confirmation dialog that states the person count, the target mailing list name, the event name if firing a sequence, and the full list of property changes, and requires an explicit confirm. Cap the batch with a configurable maximum, defaulting to 2000 people, and refuse to push past the cap without an explicit override. Loops allows 10 requests per second per team, so throttle the per person loop to around 5 requests per second with bounded concurrency, read the x-ratelimit headers, and back off with jitter on a 429 and retry. There is no bulk contact write in Loops, so the push is a throttled per person loop by design. Branch on HTTP status, not just the success boolean in the response body. Run the push server side with a live progress bar and running success and failure counts, and end on a result view listing every person with their status and failure reason plus a Retry failed only button that touches nobody who already succeeded.

Every push, including dry runs, appends one row to a Google Sheet with Append Values: timestamp, who pushed it, segment name, the segment definition as either the cohort ID or the HogQL text, person count, push mode, mailing list ID and name, the properties and values that were set, the event name if any, the dry run flag, success count, failure count, and free text notes. A Sync history tab reads that sheet back with Get Values and renders it newest first, so the team can see which audience was last pushed. Selecting a history row lets the marketer open the full definition, rerun it by loading the definition back into the builder prefilled, or diff it by re-resolving the segment now and showing how many people were added, removed, and unchanged against the recorded count.

Add a Build this segment from a description button in the builder that starts a background agent. The marketer types something like "trial users who hit the integrations page twice but never connected one, in the last 14 days". The agent explores the project schema by running small discovery queries with Execute HogQL Query to learn the real event names and person properties available, writes candidate HogQL for the description, runs it, and iterates if the result is empty or implausible. It then writes back into a review card in the builder containing the final HogQL, the matched person count, a plain language explanation of who matched and, just as importantly, who was deliberately excluded and why, and a concrete proposal for the property values to set and the event name to send. The agent writes nothing to Loops. Everything it produces is held for human review, and accepting the proposal simply loads it into the builder and push panel so it goes through the same dry run and confirmation path as a hand built segment.

Persist saved segments so a marketer can reopen a named audience with its definition and default push configuration, and remember each user's last used mailing list and dry run preference. The Google Sheet is the durable shared log. Lay the app out as a dense but legible two column workspace: the definition on the left, the live preview and push panel on the right, with Sync history as its own tab. Keep the person count visible at all times, since it is the number a marketer is judging the whole segment on.