querying-canvas-data

Use the ph bridge from @posthog/canvas-sdk, preferably ph.loadInsight(shortId, { dateRange }) with a saved insight. Ad-hoc typed query nodes via ph.query are secondary, and inline HogQL is the last resort. Declare every insight id and inlineQueries in project capabilities.

Call ph.query with a typed query node like { kind: "TrendsQuery" } or an inline HogQL string. Inline queries require capabilities.posthog.inlineQueries set to true, and you must compute date bounds explicitly rather than using now() or hardcoded intervals.

No, the canvas sandbox blocks direct network access, so fetch, posthog-js, and hand-rolled clients cannot reach PostHog. The ph bridge is the only data path, with credentials held by the host. External origins must be declared in capabilities.network.origins.

The host caps a canvas at 8 in-flight data requests and rejects the ninth. Consolidate multiple metrics into one query sliced client-side, or throttle overflow behind a concurrency limiter while keeping one state per section.

Use ph.state.get and ph.state.set with the user scope for viewer-private data or shared scope for team-visible values. Declare scopes in capabilities.posthog.state; values are capped at 64 KB serialized with 256 keys per scope.

The count field sums per-interval values, which double-counts unique users active on multiple days. Set trendsFilter display to BoldNumber on the query and read aggregated_value instead for a period-unique total.