---
title: "Run HogQL query"
method: POST
path: "/v1/projects/{project_id}/analytics/query"
tags: ["Analytics"]
---

# Run HogQL query

`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

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.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `query` string, required
  - `include_synthetic` boolean: Defaults to false. Set true only while debugging the project's explicit onboarding proof when its marked proof rows must be included.

## Response `200`

OK

- object
  - `rows` object[]: Canonical object-shaped result rows. Read response.rows; response.results is intentionally absent.
  - `columns` string[]: Display-order metadata only. Do not zip this with a PostHog results array.
  - `types` string[], nullable
  - `row_count` integer
  - `freshness` object
    - `source` string
    - `consistency` string
    - `cache_bust` boolean
    - `queried_at` string
    - `query_duration_ms` integer
    - `retry_after_ms` integer
    - `status` string
    - `next_action` string
  - `customer_data_filter` object
    - `applied` boolean, required
    - `include_synthetic` boolean, required
    - `mode` 'server_enforced' | 'disabled_by_request' | 'no_events_table_reference', required
    - `hogql_where` string, required
    - `next_action` string
  - `next_action` string

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/agentry/apis/agentry-api.md) · [All operations](https://skmtc.dev/agentry/apis/agentry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentry/apis/agentry-api/revisions/abdecddf009f?raw)