Events Retention

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

Endpoints

GET
POST
GET
GET

Retrieve organization events retention

Returns the events retention period that every project without its own period uses, the default period while none is set, and the periods an organization admin can set.

Required API key scopes

organization:read

Response


Example request

GET /api/organizations/:organization_id/events_retention_setting
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/organizations/:organization_id/events_retention_setting/

Example response

Status 200
RESPONSE
{
"organization_retention_months": 0,
"default_retention_months": 0,
"default_is_grandfathered": true,
"retention_months_choices": [
0
],
"plan_retention_months": 0,
"min_retention_months": 0,
"max_retention_months": 0,
"next_monthly_cleanup_on": "2019-08-24"
}

Create organization events retention

Sets how long every project without its own period keeps events. The period has to be one of retention_months_choices. Older events are deleted at the next monthly cleanup and can't be restored. Organization admins only.

Required API key scopes

organization:write

Request parameters

  • retention_months

Response


Example request

POST /api/organizations/:organization_id/events_retention_setting
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/organizations/:organization_id/events_retention_setting/\
-d retention_months=undefined

Example response

Status 200 The organization's new period.
RESPONSE
{
"organization_retention_months": 0,
"default_retention_months": 0,
"default_is_grandfathered": true,
"retention_months_choices": [
0
],
"plan_retention_months": 0,
"min_retention_months": 0,
"max_retention_months": 0,
"next_monthly_cleanup_on": "2019-08-24"
}
Status 400 The period isn't one of the periods an admin can set.
Status 403 The user isn't an organization admin.

Retrieve organization events retention deletion

Counts the events that the next monthly cleanup deletes if the organization keeps events for retention_months, summed over the projects without their own period. Organization admins only.

Required API key scopes

organization:readquery:read

Query parameters

  • retention_months
    integer

Response


Example request

GET /api/organizations/:organization_id/events_retention_setting/deletion_count
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/organizations/:organization_id/events_retention_setting/deletion_count/

Example response

Status 200 The count.
RESPONSE
{
"retention_months": 0,
"events_deleted": 0
}
Status 403 The user isn't an organization admin.
Status 504 The count took too long.

Retrieve organization events retention downgrade deletion

Counts the events that the deletion pass after a plan downgrade deletes if the organization's events retention drops to retention_months, whether or not deletion is rolled out to the organization yet. Sums the projects whose period is longer than retention_months. Organization admins only.

Required API key scopes

organization:readquery:read

Query parameters

  • retention_months
    integer

Response


Example request

GET /api/organizations/:organization_id/events_retention_setting/downgrade_deletion_count
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/organizations/:organization_id/events_retention_setting/downgrade_deletion_count/

Example response

Status 200 The count.
RESPONSE
{
"retention_months": 0,
"events_deleted": 0
}
Status 403 The user isn't an organization admin.
Status 504 The count took too long.