provider query POST /api/projects/{project_id}/query/
@utdk/posthog /api/projects/{project_id}/query/
query_create
DRF ViewSet mixin that gates coalesced responses behind permission checks. The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.
project_id path required
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
string

Try it

Authentication
Configure credentials for PostHog API
queryCreate
POST/api/projects/{project_id}/query/
DRF ViewSet mixin that gates coalesced responses behind permission checks. The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Parameters

required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Input

Client provided query ID. Can be used to retrieve the status or cancel the query.

Limit context for the query. Only 'posthog_ai' is allowed as a client-provided value.

Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name.

required

Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query. Example payload: ``` {"query": {"kind": "HogQLQuery", "query": "select * from events limit 100"}} ``` For more details on HogQL queries, see the [PostHog HogQL documentation](/docs/hogql#api-access).

Whether results should be calculated sync or async, and how much to rely on the cache: - `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache - `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache - `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache - `'force_blocking'` - calculate synchronously, even if fresh results are already cached - `'force_async'` - kick off background calculation, even if fresh results are already cached - `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the `query_status` response field.

Configure credentials above to enable sending.

Code snippet
Updates live as you fill in the form above.

TypeScript

import posthog from '@utdk/posthog';

await posthog.queryCreate({
  "async": "null",
  "client_query_id": "null",
  "filters_override": "null",
  "limit_context": "null",
  "name": "null",
  "refresh": "blocking",
  "variables_override": "null"
})