Analytics

Run HogQL query

Runs a bounded PostHog/HogQL read for an owner or member agent through the project's encrypted read-only PostHog Cloud OAuth connection. CI and runner credentials cannot call this endpoint. Agentry excludes onboarding-proof, rehearsal, and test rows from events table reads by default; pass include_synthetic=true only while debugging the project's explicit onboarding proof. Client code that calls it must use a request timeout of at least 45 seconds; real HogQL queries commonly take 10-30 seconds. For dashboard code, run a small fixed set of visible-view queries in a bounded parallel batch and flatten related metrics into grouped queries. Avoid unbounded fan-out over dynamic users, rows, segments, or filter values. The response always includes canonical object-shaped rows; columns is metadata for display order. Do not read response.results; Agentry does not expose PostHog's internal results array on this agent-facing endpoint. Check freshness before treating recent empty or partial reads as final; events sent directly from the customer application can take time to become queryable in PostHog Cloud.

post/v1/projects/{project_id}/analytics/query

Request

  • Base URL: https://api.agentry.sh
  • URL: https://api.agentry.sh/v1/projects/{project_id}/analytics/query
  • Auth: HTTP bearer

Path parameters

project_idstring required

Request body

querystring required
include_syntheticboolean

Defaults to false. Set true only while debugging the project's explicit onboarding proof when its marked proof rows must be included.

Response

OK

rowsobject[]

Canonical object-shaped result rows. Read response.rows; response.results is intentionally absent.

columnsstring[]

Display-order metadata only. Do not zip this with a PostHog results array.

typesstring[] nullable
row_countinteger
next_actionstring

Changes

No recorded changes to this operation across all 1 revision of this API.