Variables in endpoints

Variables let you customize endpoint results at execution time without creating multiple endpoints.

Variables in SQL-based endpoints

For SQL-based endpoints, use variables to inject values into your query at runtime.

Variables are required

If your query defines a variable, you must pass a value for it when executing the endpoint. Requests without required variables will fail. This is a safety feature to prevent accidentally returning unfiltered data to your customers.

Define variables in your query using the {variables.variable_name} syntax:

SQL
Run in PostHog
SELECT count()
FROM events
WHERE properties.$country = {variables.country}

Then pass values when executing:

Terminal
curl -X POST \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"country": "US"}}' \
  "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"

Materialization

SQL-based endpoints with variables can only be materialized in certain cases.

We're working on expanding what's possible, but for now you can only materialize a SQL-based endpoint that:

  • is using a single variable
  • and the variable is in an equality comparison with a field

For example, the following can be materialized:

SQL
Run in PostHog
select
  count()
from
  events
where
  properties.customer_name = {variables.customer_name}

But, the query below can not be materialized:

SQL
Run in PostHog
select
  count()
from
  events
where
  properties.customer_name = {variables.customer_name}
  and properties.$os = {variables.os}
  and toDate(timestamp) > {variables.from_date}

Variables in insight-based endpoints

For insight-based endpoints, variables work differently. Instead of defining them in your query, certain magic variables are automatically available based on your insight configuration.

The breakdown property variable

If your insight has a single breakdown configured, the breakdown property name automatically becomes a variable. For example, if your TrendsQuery breaks down by $browser, you can filter results by passing that property as a variable:

Note: The breakdown variable is only available for insights with a single breakdown. Insights with multiple breakdowns can still be used as endpoints, but you will not be able to filter by the variables.

Terminal
curl -X POST \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"$browser": "Chrome"}}' \
  "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"

This filters the results to only return data where $browser equals "Chrome".

Breakdown variables work with:

  • TrendsQuery
  • FunnelsQuery
  • RetentionQuery

Date variables

For non-materialized insight endpoints, you can also use date_from and date_to variables to filter by date:

Terminal
curl -X POST \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"date_from": "2024-01-01", "date_to": "2024-01-31"}}' \
  "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"

You can combine date variables with the breakdown variable:

Terminal
curl -X POST \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"$browser": "Chrome", "date_from": "2024-01-01", "date_to": "2024-01-31"}}' \
  "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"

Materialization

Materialized insight-based endpoints only support the breakdown property variable. Date variables (date_from, date_to) are not available for materialized endpoints because the data is pre-computed.

If your insight has a breakdown, you can still filter by that property:

Terminal
curl -X POST \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"$browser": "Chrome"}}' \
  "<ph_app_host>/api/projects/{project_id}/endpoints/{endpoint_name}/run"

Community questions

Was this page useful?

Questions about this page? or post a community question.