Insights
For instructions on how to authenticate to use this endpoint, see API overview.
Override the default in ModelViewSet that allows callers to destroy a model instance.
Endpoints
List all insights
Path Parameters
- project_idstring
Query Parameters
- created_byinteger
- formatstringOne of:
"csv"
"json"
- limitinteger
- offsetinteger
- short_idstring
Response
Request
GET
/api/projects/:project_id/insights/
Response
{"count": 123,"next": "http://api.example.org/accounts/?offset=400&limit=100","previous": "http://api.example.org/accounts/?offset=200&limit=100","results": [{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}]}
Create insights
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- namestring
- derived_namestring
- filtersobject
- orderinteger
- deletedboolean
- dashboardsarray
A dashboard ID for each of the dashboards that this insight is displayed on.
- descriptionstring
- tagsarray
- favoritedboolean
- savedboolean
Response
Request
POST
/api/projects/:project_id/insights/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights
When loading an insight for a dashboard pass a from_dashboard
query parameter containing the dashboard ID
e.g. "/api/projects/{team_id}/insights/{insight_id}?from_dashboard={dashboard_id}"
Insights can be added to more than one dashboard, this allows the insight to be loaded in the correct context.
Using the correct cache and enriching the response with dashboard specific config (e.g. layouts or colors)
Path Parameters
- idinteger
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/:id/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Update insights
Path Parameters
- idinteger
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- namestring
- derived_namestring
- filtersobject
- orderinteger
- deletedboolean
- dashboardsarray
A dashboard ID for each of the dashboards that this insight is displayed on.
- descriptionstring
- tagsarray
- favoritedboolean
- savedboolean
Response
Request
PATCH
/api/projects/:project_id/insights/:id/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Delete insights
Path Parameters
- idinteger
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request
DELETE
/api/projects/:project_id/insights/:id/
Response
No responseRetrieve insights activity retrieve
Path Parameters
- idinteger
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/:id/activity/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Create insights viewed
Path Parameters
- idinteger
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- namestring
- derived_namestring
- filtersobject
- orderinteger
- deletedboolean
- dashboardsarray
A dashboard ID for each of the dashboards that this insight is displayed on.
- descriptionstring
- tagsarray
- favoritedboolean
- savedboolean
Response
Request
POST
/api/projects/:project_id/insights/:id/viewed/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights activity
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/activity/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights funnel
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/funnel/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Create
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- eventsarray
Events to filter on. One of
events
oractions
is required. - actionsarray
Actions to filter on. One of
events
oractions
is required. - properties
Filter events by event property, person property, cohort, groups and more.
- filter_test_accountsboolean
Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.
- date_fromstringDefault:
-7d
What date to filter the results from. Can either be a date
2021-01-01
, or a relative date, like-7d
for last seven days,-1m
for last month,mStart
for start of the month oryStart
for the start of the year. - date_tostringDefault:
-7d
What date to filter the results to. Can either be a date
2021-01-01
, or a relative date, like-7d
for last seven days,-1m
for last month,mStart
for start of the month oryStart
for the start of the year. - breakdownstring
A property or cohort to break down on. You can select the type of the property with breakdown_type.
event
(default): a property keyperson
: a person property keycohort
: an array of cohort IDs (ie[9581,5812]
)
- breakdown_typestringDefault:
event
One of:"event"
"person"
"cohort"
"group"
"session"
Type of property to break down on.
- funnel_window_intervalintegerDefault:
14
Funnel window size. Set in combination with funnel_window_interval, so defaults to 'days'.
- funnel_window_interval_typestringDefault:
days
One of:"DAY"
"MINUTE"
"HOUR"
"WEEK"
"MONTH"
The type of interval. Used in combination with
funnel_window_intervals
. - funnel_viz_typestringDefault:
steps
One of:"trends"
"time_to_convert"
"steps"
The visualisation type.
steps
Track instances progress between steps of the funneltrends
Track how this funnel's conversion rate is trending over time.time_to_convert
Track how long it takes for instances to convert
- funnel_order_typestringDefault:
ordered
One of:"strict"
"unordered"
"ordered"
ordered
- Step B must happen after Step A, but any number events can happen between A and B.strict
- Step B must happen directly after Step A without any events in between.unordered
- Steps can be completed in any sequence.
- exclusionsarray
Exclude users/groups that completed the specified event between two specific steps. Note that these users/groups will be completely excluded from the entire funnel.
- aggregation_group_type_indexinteger0
Aggregate by users or by groups.
0
means user,>0
means a group. See interface for the corresponding ID of the group. - breakdown_limitintegerDefault:
10
- funnel_window_daysintegerDefault:
14
(DEPRECATED) Funnel window size in days. Use
funnel_window_interval
andfunnel_window_interval_type
Response
Request
POST
/api/projects/:project_id/insights/funnel/
Response
{"is_cached": true,"last_refresh": "2019-08-24T14:15:22Z","timezone": "Africa/Abidjan","result": [{"count": 0,"action_id": "string","average_conversion_time": 0,"median_conversion_time": 0,"converted_people_url": "string","dropped_people_url": "string","order": "string"}]}
Retrieve insights funnel correlation
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/funnel/correlation/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Create insights funnel correlation
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- namestring
- derived_namestring
- filtersobject
- orderinteger
- deletedboolean
- dashboardsarray
A dashboard ID for each of the dashboards that this insight is displayed on.
- descriptionstring
- tagsarray
- favoritedboolean
- savedboolean
Response
Request
POST
/api/projects/:project_id/insights/funnel/correlation/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights path
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/path/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Create insights path
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- namestring
- derived_namestring
- filtersobject
- orderinteger
- deletedboolean
- dashboardsarray
A dashboard ID for each of the dashboards that this insight is displayed on.
- descriptionstring
- tagsarray
- favoritedboolean
- savedboolean
Response
Request
POST
/api/projects/:project_id/insights/path/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights retention
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/retention/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Retrieve insights trend
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Response
Request
GET
/api/projects/:project_id/insights/trend/
Response
{"id": 0,"short_id": "string","name": "string","derived_name": "string","filters": {"property1": null,"property2": null},"filters_hash": "string","order": -2147483648,"deleted": true,"dashboards": [0],"last_refresh": "string","refreshing": true,"result": "string","created_at": "2019-08-24T14:15:22Z","created_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"description": "string","updated_at": "2019-08-24T14:15:22Z","tags": [null],"favorited": true,"saved": true,"last_modified_at": "2019-08-24T14:15:22Z","last_modified_by": {"id": 0,"uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f","distinct_id": "string","first_name": "string","email": "user@example.com"},"is_sample": true,"effective_restriction_level": 21,"effective_privilege_level": 21,"timezone": "string"}
Create
Path Parameters
- project_idstring
Query Parameters
- formatstringOne of:
"csv"
"json"
Request Parameters
- eventsarray
Events to filter on. One of
events
oractions
is required. - actionsarray
Actions to filter on. One of
events
oractions
is required. - properties
Filter events by event property, person property, cohort, groups and more.
- filter_test_accountsboolean
Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.
- date_fromstringDefault:
-7d
What date to filter the results from. Can either be a date
2021-01-01
, or a relative date, like-7d
for last seven days,-1m
for last month,mStart
for start of the month oryStart
for the start of the year. - date_tostringDefault:
-7d
What date to filter the results to. Can either be a date
2021-01-01
, or a relative date, like-7d
for last seven days,-1m
for last month,mStart
for start of the month oryStart
for the start of the year. - breakdownstring
A property or cohort to break down on. You can select the type of the property with breakdown_type.
event
(default): a property keyperson
: a person property keycohort
: an array of cohort IDs (ie[9581,5812]
)
- breakdown_typestringDefault:
event
One of:"event"
"person"
"cohort"
"group"
"session"
Type of property to break down on.
- displaystringDefault:
ActionsLineGraph
One of:"ActionsLineGraph"
"ActionsLineGraphCumulative"
"ActionsTable"
"ActionsPie"
"ActionsBar"
"ActionsBarValue"
"WorldMap"
"BoldNumber"
How to display the data. Will change how the data is returned.
- formulastring
Combine the result of events or actions into a single number. For example
A + B
or(A-B)/B
. The letters correspond to the order of theevents
oractions
lists. - compareboolean
For each returned result show the current period and the previous period. The result will contain
compare:true
and acompare_label
with eithercurrent
orprevious
.
Response
Request
POST
/api/projects/:project_id/insights/trend/
Response
{"is_cached": true,"last_refresh": "2019-08-24T14:15:22Z","timezone": "Africa/Abidjan","result": [{"data": [0],"days": ["2019-08-24"],"labels": ["string"],"filter": {"events": [{"id": "string","properties": [{"type": "AND","values": [{"key": "string","value": "string","operator": "exact","type": "event"}]}],"math": "total"}],"actions": [{"id": "string","properties": [{"type": "AND","values": [{"key": "string","value": "string","operator": "exact","type": "event"}]}],"math": "total"}],"properties": {"type": "AND","values": [{"key": "string","value": "string","operator": "exact","type": "event"}]},"filter_test_accounts": false,"date_from": "-7d","date_to": "-7d"},"label": "string"}]}