insights

get/api/projects/{project_id}/insights/{id}/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/insights/{id}/
  • Auth: HTTP bearer

Path parameters

integer required
OR
string required

Numeric primary key or 8-character short_id (for example AaVQ8Ijw) identifying the insight.

project_idstring required

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

Query parameters

filters_overridestring

Object (or pre-encoded JSON string) to override the insight's filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged — pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., date_from, date_to, properties). Ignored when accessed via a sharing token.

format'csv' | 'json'
from_dashboardinteger

Only if loading an insight in the context of a dashboard: The relevant dashboard's ID. When set, the specified dashboard's filters and date range override will be applied.

include_dashboardsboolean

Opt in to receiving the deprecated dashboards field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use dashboard_tiles instead.

refresh'async' | 'async_except_on_cache_miss' | 'blocking' | 'force_async' | 'force_blocking' | 'force_cache' | 'lazy_async'

Whether to refresh the insight, how aggresively, and if sync or async:

  • 'force_cache' - return cached data or a cache miss; always completes immediately as it never calculates
  • '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 Background calculation can be tracked using the query_status response field.
variables_overridestring

Object (or pre-encoded JSON string) to override the insight's HogQL variables for this request only (not persisted). Format: {"<variable_id>": {"code_name": "<code_name>", "variableId": "<variable_id>", "value": <new_value>}}. Each entry must include code_name — partial entries are silently dropped. The simplest workflow is to call insight-get first, copy the matching entry from the response, and mutate value. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token.

Response

idinteger required
short_idstring required
namestring nullable
derived_namestring nullable
orderinteger nullable
deletedboolean
dashboardsinteger[] 
    DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    This field is omitted from session-authenticated responses unless `include_dashboards=true`
    is passed. Once opt-in enforcement is enabled, API-token callers (personal API keys, OAuth)
    must opt in the same way. Do not rely on it being present.
last_refreshstring date-time nullable required
The datetime this insight's results were generated.
If added to one or more dashboards the insight can be refreshed separately on each.
Returns the appropriate last_refresh datetime for the context the insight is viewed in
(see from_dashboard query parameter).
cache_target_agestring date-time nullable required

The target age of the cached results for this insight.

next_allowed_client_refreshstring date-time nullable required
The earliest possible datetime at which we'll allow the cached results for this insight to be refreshed
by querying the database.
resultunknown required
hasMoreboolean nullable required
columnsstring[] nullable required
created_atstring date-time nullable required
descriptionstring nullable
updated_atstring date-time required
favoritedboolean
last_modified_atstring date-time required
is_sampleboolean required
effective_restriction_level21 | 37 required
  • 21 - Everyone in the project can edit
  • 37 - Only those invited to this dashboard can edit
effective_privilege_level21 | 37 required
  • 21 - Can view dashboard
  • 37 - Can edit dashboard
user_access_levelstring nullable required

The effective access level the user has for this object

timezonestring nullable required

The timezone this chart is displayed in.

is_cachedboolean required
query_statusunknown required
hogqlstring nullable required
query_scanunknown required
_create_in_folderstring
last_viewed_atstring date-time nullable required

Changes

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