Query

For instructions on how to authenticate to use this endpoint, see API overview.

Create query

This is the main endpoint for querying data from PostHog. It is used for many kinds of queries including TrendsQuery, FunnelsQuery, ActorsQuery, EventsQuery, and more.

The most useful for you is likely HogQLQuery. This enables you to query PostHog using HogQL. For example, to get events where the $current_url contains blog:

curl \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  <ph_app_host>/api/projects/:project_id/query/ \
  -d '{
        "query": {
          "kind": "HogQLQuery",
          "query": "select properties.$current_url from events where properties.$current_url like '\''%/blog%'\'' limit 100"
        }
      }'

It is also useful for querying non-event data like persons, data warehouse, session replay metadata, and more. For example, to get a list of all people with the email property:

curl \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  <ph_app_host>/api/projects/:project_id/query/ \
  -d '{
        "query": {
          "kind": "HogQLQuery",
          "query": "select properties.email from persons where properties.email is not null"
        }
      }'

Note: This endpoint is limited to 10,000 rows at 120 requests per hour. If you need more, use batch exports.

To learn more, read the query endpoint code on GitHub or search for query requests in your browser's network tab in PostHog.

Required API key scopes

query:read

Path parameters

  • project_id
    string

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

Request parameters

  • async

    (Experimental) Whether to run the query asynchronously. Defaults to False. If True, the id of the query can be used to check the status and to cancel it.

  • client_query_id

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

  • query

    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.

  • refresh

Response


Request

POST /api/projects/:project_id/query
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/query/\
	-d query=undefined

Response

Status 200
RESPONSE
{}

Retrieve query

(Experimental)

Required API key scopes

query:read

Path parameters

  • id
    string
  • project_id
    string

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

Response


Request

GET /api/projects/:project_id/query/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/query/:id/

Response

Status 200
RESPONSE
{
  "query_status": {
    "complete": false,
    "end_time": null,
    "error": false,
    "error_message": null,
    "expiration_time": null,
    "id": "string",
    "query_async": true,
    "query_progress": null,
    "results": null,
    "start_time": null,
    "task_id": null,
    "team_id": 0
  }
}

Delete query

(Experimental)

Required API key scopes

query:read

Path parameters

  • id
    string
  • project_id
    string

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

Request

DELETE /api/projects/:project_id/query/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/query/:id/

Response

Status 204 Query cancelled

Retrieve query draft sql

Path parameters

  • project_id
    string

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

Request

GET /api/projects/:project_id/query/draft_sql
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    https://app.posthog.com/api/projects/:project_id/query/draft_sql/

Response

Status 200 No response body

Questions?

Was this page useful?