references/graph-schema.md · 24000
dius preview.
internal-event(flag-gated) —{ "type": "internal-event", "filters": { "source": "internal-events", "events": [{ "id": "<event>", "type": "events" }], "properties": [<cond>] } }. Fires once for each matching event on the internal-events stream;filters.eventsmust name at least one allowed event id. Runs have no associated person, so person-dependent steps are unavailable. Test-run with an event named infilters.eventsand no person; any other event name is skipped at the trigger. The Slack trigger is this with$slack_message_receivedinfilters.events: the run's event carries propertiesintegration_id,channel,channel_type,slack_team_id,user,bot_id,app_id,subtype,text,ts,thread_ts,is_thread_reply,is_ext_shared_channel, andslack_event(the raw Slack payload). A workflow leaving draft must include one exactchannelproperty filter whose value contains one or more channel IDs; several IDs match any listed channel. The GitHub trigger uses$github_event_receivedand requires exactrepositoryandevent_typefilters.
Trigger masking (throttling an event trigger)
trigger_masking is a top-level workflow field (not an action) that throttles an already-matching event trigger — it dedups/samples firings, it does not decide who enters.
"trigger_masking": { "hash": "{person.id}", "ttl": 3600, "threshold": null }
hash— HogQL template defining the dedup key."{person.id}"= once per person.ttl— seconds to suppress repeats of the same hash (60–94608000).threshold?— fire once per N matches of the same hash (a sampler: N=3 fires on the 1st, 4th, 7th…). Omit to fire once then suppress withinttl.- Don't send
bytecode— compiled server-side fromhash.
Condition shape (<cond>)
Property conditions used in trigger/action filters, branch conditions, and conversion:
{ "key": "plan", "value": ["pro"], "operator": "exact", "type": "person" }
type is event | person | group. Never include bytecode — the server compiles it.
Edges
{ "from": "source_id", "to": "target_id", "type": "continue", "index": 0 }
type: "continue"— fall-through: the sequential next step, or the no-match path out of aconditional_branch. For await_until_conditionit is themax_wait_durationtimeout path.type: "branch"— requiresindex, matchingconfig.conditions[index]on aconditional_branch. Await_until_conditionresolves (itsconditionmatches or aneventsentry fires) out thebranchedge atindex: 0.- Every non-exit node needs a reachable next action via an outgoing edge, or execution fails with "No next action found".
- A
conditional_branchwith N conditions typically has Nbranchedges (index: 0..N-1) plus onecontinueedge for the no-match path. - A
wait_until_conditionneeds abranchedge atindex: 0(resolution) and acontinueedge (timeout). Without theindex: 0branch it only ever advances on timeout, never on the event/condition firing.
function* inputs
Inputs are keyed by the template's input schema, each wrapped in {value: ...}:
"inputs": { "url": { "value": "https://example.com/hook" } }
- Wrap values in
{value: ...}. A flat string won't enable templating. - Templating uses single-curly
{person.x}/{event.x}inside the value string. Liquid-style{{ ... }}is rejected on hog-templated fields ("Placeholders are not allowed in this context") — the only fields that accept Liquid are ones whose input schema declarestemplating: liquid(the email input onfunction_emaildoes; most others don't). - Dictionary input values are template strings too — write booleans/numbers as single-expression templates:
"{true}","{42}", which evaluate to the typed value. - Required inputs must be present, or create fails with "This field is required".
Discovering function templates (do this, don't guess)
The set of available function templates and their required inputs is live data, not something to hardcode — it changes as integrations are added. For a function node:
cdp-function-templates-list(filtertype=destination) to find the right template and itsid.cdp-function-templates-retrievewith that id to read itsinputs_schema— the exact keys, types, and which are required.- Build
inputsfrom that schema. Atemplate_idnot in the live list fails with "Template not found".
function_email, function_sms, and function_push are the exception — their template_id is the fixed literal template-email / template-twilio / template-native-push, so you don't look the template_id up, and you can omit it entirely: the server infers the literal from the step type. A saved email template's UUID goes in template_uuid alongside the literal, never in template_id (a UUID sent as template_id is moved into template_uuid automatically). For function_email, referencing a template means you only author from/to: the server materializes the template's body at save (see the action-types table). function_push still has variable inputs (notably channels), so retrieve its inputs_schema even though the id is fixed.
function_push worked example
Retrieve template-native-push with cdp-function-templates-retrieve for the full inputs_schema (it has many optional Android/iOS keys), but the core shape is:
{
"id": "push_1",
"name": "Re-engagement push",
"type": "function_push",
"config": {
"template_id": "template-native-push",
"inputs": {
"distinctId": { "value": "{event.distinct_id}" },
"channels": { "value": [6, 7] },
"title": { "value": "Notification from {event.event}" },
"body": { "value": "Hi {{ person.properties.first_name }}, come finish setting up.", "templating": "liquid" }
}
}
}
channelsis anintegration_multiinput: itsvalueis an array of integration id numbers (e.g.[6, 7]), not objects. Find the FCM/APNs integration ids withintegrations-list(look forkindfirebase/apns); at least one is required or the send throws "No push channel configured".- Templating differs per input.
bodyis liquid — interpolate with{{ person.x }}/{{ event.x }}(double braces) and set"templating": "liquid".titleand the other string inputs are hog — use{event.x}/{person.x}(single braces). The wrong brace style leaves the expression as a literal. - Required:
distinctId,channels,title. Optional:body,image,data,ttlSeconds,android_*,ios_*(retrieve theinputs_schemafor the full set). - Never hand-author
bytecode— the server compiles it fromvalue. Omitordertoo: the editor lays fields out in the template'sinputs_schemaorder (fixed and consistent), not by theorderon your inputs, so leaving it off doesn't change the form. Push has no delivered/opened/clicked signal (FCM/APNs respond synchronously), so a successful send means "accepted for delivery", nothing more.
Replay Vision step
Replay Vision is PostHog's AI that watches session recordings. It replays a session as video, together with its events, and answers a question about it. Each scan uses credits from the project's Replay Vision quota.
A function node with template_id: "template-posthog-replay-vision" scans the trigger event's session and waits for the answer. Use it when the next step depends on what happened in the session, which event properties alone can't tell, for example to add session context to a Slack alert or to branch on whether the user struggled. The project must record sessions, and the trigger event must carry a $session_id.
{
"id": "vision_1",
"name": "Did checkout fail?",
"type": "function",
"config": {
"template_id": "template-posthog-replay-vision",
"inputs": {
"analysis": { "value": { "type": "monitor", "prompt": "Did the user hit an error during checkout?" } }
}
},
"output_variable": { "key": "replay_vision" }
}
-
analysisis a literal object, not a template. Never set"templating"on it, and never put{...}expressions in it. Itsvaluetakes one of these shapes:|
type| Required keys | What the step answers | | ------------ | ----------------------------------------------- | --------------------------------------------------------- | |monitor|prompt| A yes/no verdict on the question inprompt. | |classifier|prompt,tags(1 to 100 category strings) | Which of the categories intagsfit the session. | |scorer|prompt,scale: {"min": <num>, "max": <num>}| A score on the scale.maxmust be greater thanmin. | |summarizer|prompt| A title, a summary, and chapters. | |scanner|scanner_id(a saved scanner's UUID) | The saved scanner's answer, with its own type and prompt. | -
The inline types take the same optional settings as a saved scanner of that type. See the
creating-replay-vision-scannersskill. Find saved scanners with thevision-scannerstools. The step refuses an experiment scanner, because it samples the experiment's variants evenly, which one triggered session can't do. -
session_iddefaults to{event.properties.$session_id}. Leave it unset unless the session ID is in another property. -
wait_for_session_enddefaults totrue, which scans the recording after the session has been quiet for 35 minutes. Set it tofalseonly when the trigger event comes after the session ended. -
The step result is
{"state", "output", "warnings"}.stateissucceeded,failed,skipped,ineligibleorlost.outputis the scanner's answer:verdict,tagsorscorewithreasoningfor a monitor, classifier or scorer, andtitle,summaryandchaptersfor a summarizer. Every type also returnsconfidence. Useoutput_variableto keep the result, then branch on it. Whenoutputis null,warningssays why: used-up credits, a session too short or too long to scan, or a failed scan. -
Main environment only. The server refuses the step in a child environment of a project.
-
Daily caps. Each workflow can start 100 scans a day, and the project 500, unless the project settings change
replay_vision_scan_rate_limit_per_dayandreplay_vision_scan_team_rate_limit_per_day. Past a cap the step returnsstate: "skipped"and the workflow continues. -
Access. The token needs
session_recording:read(or:write) andreplay_scanner:write, and the user needs access to recordings and to the saved scanner. Without them, the save fails with a message that names what is missing.
Opt out of messages step
A function node with template_id: "template-posthog-opt-out-of-messages" adds the run's recipient to the opt-out list for one message category, or for all marketing messages. Later email, SMS and push steps for that category skip the recipient. Use it whenever a workflow has to opt someone out. Don't build this with a webhook step that calls messaging_preferences/add_opt_out/ with an API key: that call breaks when the key's owner leaves or the key rotates, and its failures only show as webhook errors.
{
"id": "opt_out_1",
"name": "Opt out of product updates",
"type": "function",
"on_error": "abort",
"config": {
"template_id": "template-posthog-opt-out-of-messages",
"inputs": {
"category_id": { "value": "<message category id>" },
"identifier": { "value": "{person.properties.email}" }
}
}
}
category_idis a literal, not a template. Use a marketing message category'sid(UUID), listed bymessage-categories-list, or"$all"for all marketing messages. If the category doesn't exist yet and the user's request covers creating it, for example an import that brings its own categories, create it withmessage-categories-create. Otherwise ask the user for it rather than guess. Never put{...}expressions in it. A save with a category the project doesn't have fails.identifieris who to opt out. It defaults to{person.properties.email}. Use the same value as the recipient of the email step it should suppress, because opt-outs match the recipient exactly.- Only marketing categories work, because transactional messages ignore opt-outs. A save with a transactional category fails.
- The step fails, and the workflow log says why, when
identifieris empty or the category was deleted. It never passes silently. - Set
"on_error": "abort"on the node. Without it, a failed opt-out continues to the next step, which may send the message the person asked to stop. - Running it again for someone who is already opted out succeeds and logs "Already opted out".
- The step is behind the
workflow-opt-out-of-messages-actionfeature flag. Without the flag, the save fails with "Template not found".
Duration strings (delay_duration, max_wait_duration)
Must match ^\d*\.?\d+[dhms]$ — a number plus unit s | m | h | d. Examples: 30s, 30m, 2h, 1d, 1.5d (=36h).
- No ISO-8601. Fractions are allowed in every unit.
- Per-unit caps:
s≤60,m≤60,h≤24, andd≤365 fordelay_durationandmax_delay_durationbutd≤30 for a wait'smax_wait_duration. A save over a cap is rejected, so use the larger unit (90m→1.5h). Workflows saved before the check may still store an over-cap value, which runs at the cap.
Waiting until a date (delay_until)
A delay waits either a fixed span or until a date carried by the person or the event. Use delay_until when the date differs per person, which a duration cannot express (a trial expiry, a renewal date, a booked appointment).
{
"id": "delay_1",
"type": "delay",
"config": {
"delay_until": { "expression": "person.properties.trial_expiration_at", "offset": "-1d" },
"max_delay_duration": "30d"
}
}
- Exactly one of
delay_durationanddelay_until. Both together are rejected; so is neither. expressionis HogQL resolving to a datetime. An ISO string, aHogDateTime, and unix seconds all resolve to the same instant, so a stored date works whichever shape the customer set it in. A bare number is read as seconds: a millisecond timestamp (whatDate.now()and most SDKs produce) is rejected rather than read as a date tens of thousands of years out. Divide it by 1000 in the expression, or store the date as an ISO string.offsetshifts that instant and is signed:^-?\d*\.?\d+[dhms]$.-1dis a day before the date,2his two hours after. Omit it to wait for the date itself. Keep the arithmetic here rather than in the expression, so the builder can still read the step back as a property plus an offset.- Unlike
delay_duration, an offset is not clamped per unit:-48hmeans 48 hours, not 24.max_delay_durationbounds the wait instead. timezone,use_person_timezoneandfallback_timezonework as they do onwait_until_time_window, and decide which zone a date with no offset of its own is read in (a bare2026-03-01, or2026-03-01T09:00:00). A date that states an offset, aHogDateTime, and unix seconds are absolute and ignore them. DefaultUTC, so a date-only value means midnight UTC unless you set a zone.max_delay_durationcaps how far past the step's start the wait may run (default30d, same duration rules as above). It exists so a far-future date cannot park a run indefinitely.- Never send
bytecode. The server compiles the expression at save time and discards anything the client sent. A broken expression fails the save with the parse error. - The expression is re-read on every wake, not only on entry, and the only wake a parked delay schedules is the instant it computed. So a date that moves further out is honored: the run wakes at the old instant and parks again to the new one. A date that moves closer is not: nothing wakes the run early, so it waits for the original instant and then continues at once, later than the new date asked for.
- A date that cannot be resolved aborts the run whatever
on_errorsays, because a wait that cannot work out when to act has nothing safe to fall through to. - A person property is
person.properties.<key>; an event property isproperties.<key>, with noevent.prefix. The expression runs against the same globals as a filter, whereeventis the event's name, soevent.properties.<key>resolves to nothing and aborts the run. - The builder writes those two shapes (bracketed when the key is not a bare identifier). Any other expression saves fine but shows in the editor as a read-only custom expression instead of a property pick.
Conversion & exit condition
exit_condition:exit_only_at_end(default),exit_on_conversion,exit_on_trigger_not_matched,exit_on_trigger_not_matched_or_conversion.- The
…conversionvariants require aconversiongoal with two slots plus a window:filters— property conditions only, an array[{key, value, operator, type}, ...](empty array = any event in the window converts).events— event-based goals,[{ "filters": { "events": [{ "id": "<event>", "name": "<event>", "type": "events" }] } }].window— how long after entry a conversion still counts, as a duration string ("7d","12h","30m","45s"), max"365d". Omit it (ornull) for the default 90-day window.- There is no minutes form. The server drops a
window_minuteskey without an error, so a window sent that way silently becomes the 90-day default.
- An event goal goes in
events, never infilters. An event object stuffed intofiltersis invisible to the conversion matcher and breaks the conversion picker. Without a goal the…conversionexit is a silent no-op. Server compiles the bytecode.
Pre-submit checklist
- [ ] Exactly one
type: "trigger"action; usually exactly oneexit. - [ ] Every action
typeandconfigmatches a row above (no types outside the supported set). - [ ]
on_erroris onlycontinueorabort. - [ ]
function_email.template_id == "template-email",function_sms.template_id == "template-twilio",function_push.template_id == "template-native-push". - [ ] A
webhook/manualtrigger setstemplate_id == "template-source-webhook"(atracking_pixeluses"template-source-webhook-pixel") — these are built-in source templates, not catalog lookups. - [ ] That trigger's
inputs.event/inputs.distinct_idmatch its own type:{request.body.*}forwebhook,$workflow_triggered+{request.body.user_id}formanual,{request.query.ph_*}fortracking_pixel. The wrong pair saves fine and then fails at trigger time. - [ ] Every non-exit node has an outgoing edge;
branchedges have anindexmatching a condition. - [ ] Every
conditional_branch/wait_until_conditioncondition is wrapped:{filters: {properties: [...]}}, not{properties: [...]}. - [ ] All durations match
^\d*\.?\d+[dhms]$and stay within the per-unit caps. - [ ] Every
delaysets exactly one ofdelay_durationanddelay_until, and nodelay_untilcarries hand-writtenbytecode. - [ ] Function inputs are
{key: {value: ...}}; no hand-writtenbytecodeanywhere; no top-leveltriggerfield set. - [ ] A Replay Vision step's
analysisvalue is a literal object of one of the five shapes, with notemplating.