Insights
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
POST | |
DELETE | |
POST | |
GET | |
PATCH | |
DELETE | |
GET | |
GET | |
POST | |
GET | |
POST |
List all insights
Required API key scopes
insight:read
Path parameters
- project_idstring
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
- basicboolean
Return basic insight metadata only (no results, faster).
- created_byinteger
- formatstringOne of:
"csv"
"json"
- limitinteger
Number of results to return per page.
- offsetinteger
The initial index from which to return the results.
- refreshstringDefault:
force_cache
One of:"async"
"async_except_on_cache_miss"
"blocking"
"force_async"
"force_blocking"
"force_cache"
"lazy_async"
Whether to refresh the retrieved insights, 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 thequery_status
response field.
- short_idstring
Response
Example request
GET
/api /projects /:project_id /insights
Example response
Status 200
Create insights
Required API key scopes
insight:write
Path parameters
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Request parameters
- namestring
- derived_namestring
- queryobject
- orderinteger
- deletedboolean
- dashboardsarray
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.
- descriptionstring
- tagsarray
- favoritedboolean
- _create_in_folderstring
Response
Example request
POST
/api /projects /:project_id /insights
Example response
Status 201
List all insights sharing
Required API key scopes
sharing_configuration:read
Path parameters
- insight_idinteger
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
Example request
GET
/api /projects /:project_id /insights /:insight_id /sharing
Example response
Status 200
Create insights sharing passwords
Create a new password for the sharing configuration.
Required API key scopes
sharing_configuration:write
Path parameters
- insight_idinteger
- project_idstring
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
- enabledboolean
- settings
- password_requiredboolean
Response
Example request
POST
/api /projects /:project_id /insights /:insight_id /sharing /passwords
Example response
Status 200
Delete insights sharing passwords
Delete a password from the sharing configuration.
Required API key scopes
sharing_configuration:write
Path parameters
- insight_idinteger
- password_idstring
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
Example request
DELETE
/api /projects /:project_id /insights /:insight_id /sharing /passwords /:password_id
Example response
Status 204 No response body
Create insights sharing refresh
Required API key scopes
sharing_configuration:write
Path parameters
- insight_idinteger
- project_idstring
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
- enabledboolean
- settings
- password_requiredboolean
Response
Example request
POST
/api /projects /:project_id /insights /:insight_id /sharing /refresh
Example response
Status 200
Retrieve insights
Required API key scopes
insight:read
Path parameters
- idinteger
A unique integer value identifying this insight.
- project_idstring
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
- formatstringOne of:
"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.
- refreshstringDefault:
force_cache
One of:"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 thequery_status
response field.
Response
Example request
GET
/api /projects /:project_id /insights /:id
Example response
Status 200
Update insights
Required API key scopes
insight:write
Path parameters
- idinteger
A unique integer value identifying this insight.
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Request parameters
- namestring
- derived_namestring
- queryobject
- orderinteger
- deletedboolean
- dashboardsarray
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.
- descriptionstring
- tagsarray
- favoritedboolean
- _create_in_folderstring
Response
Example request
PATCH
/api /projects /:project_id /insights /:id
Example response
Status 200
Delete insights
Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
Required API key scopes
insight:write
Path parameters
- idinteger
A unique integer value identifying this insight.
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Example request
DELETE
/api /projects /:project_id /insights /:id
Example response
Status 405 No response body
Retrieve insights activity retrieve
Required API key scopes
activity_log:read
Path parameters
- idinteger
A unique integer value identifying this insight.
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Example request
GET
/api /projects /:project_id /insights /:id /activity
Example response
Status 200 No response body
Retrieve insights activity
Required API key scopes
activity_log:read
Path parameters
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Example request
GET
/api /projects /:project_id /insights /activity
Example response
Status 200 No response body
Create insights cancel
Path parameters
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Request parameters
- namestring
- derived_namestring
- queryobject
- orderinteger
- deletedboolean
- dashboardsarray
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.
- descriptionstring
- tagsarray
- favoritedboolean
- _create_in_folderstring
Example request
POST
/api /projects /:project_id /insights /cancel
Example response
Status 200 No response body
Retrieve insights my last viewed
Returns basic details about the last 5 insights viewed by this user. Most recently viewed first.
Path parameters
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Example request
GET
/api /projects /:project_id /insights /my_last_viewed
Example response
Status 200 No response body
Create insights viewed
Update insight view timestamps. Expects: {"insight_ids": [1, 2, 3, ...]}
Required API key scopes
insight:read
Path parameters
- project_idstring
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
- formatstringOne of:
"csv"
"json"
Request parameters
- namestring
- derived_namestring
- queryobject
- orderinteger
- deletedboolean
- dashboardsarray
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.
- descriptionstring
- tagsarray
- favoritedboolean
- _create_in_folderstring
Example request
POST
/api /projects /:project_id /insights /viewed