Feature flags API Reference

Feature flags

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`GET`
`POST`
`POST`
`POST`
`POST`
`GET`
`GET`
`GET`
`POST`
`GET`
`GET`
`GET`
`POST`

List all feature flags

This endpoint returns a list of feature flags and their details like name, key, variants, rollout_percentage, and more.

To evaluate and determine the value of flags for a given user, use the flags endpoint instead.

Required API key scopes

feature_flag:read

Path parameters

project_id
string

Query parameters

active
string
One of: "STALE""false""true"
created_by_id
string
evaluation_runtime
string
One of: "both""client""server"
excluded_properties
string
has_evaluation_tags
string
One of: "false""true"
limit
integer
offset
integer
search
string
tags
string
type
string
One of: "boolean""experiment""multivariant"

Response

Example request

GET /api/projects/:project_id/feature_flags

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/

Example response

Status 200

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,
      "name": "string",
      "key": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "deleted": true,
      "active": true,
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {
          "property1": null,
          "property2": null
        },
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0,
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {
          "property1": null,
          "property2": null
        },
        "role_at_organization": "engineering"
      },
      "is_simple_flag": true,
      "rollout_percentage": 0,
      "ensure_experience_continuity": true,
      "experiment_set": "string",
      "surveys": {
        "property1": null,
        "property2": null
      },
      "features": {
        "property1": null,
        "property2": null
      },
      "rollback_conditions": null,
      "performed_rollback": true,
      "can_edit": true,
      "tags": [
        null
      ],
      "evaluation_tags": [
        null
      ],
      "usage_dashboard": 0,
      "analytics_dashboards": [
        0
      ],
      "has_enriched_analytics": true,
      "user_access_level": "string",
      "creation_context": "feature_flags",
      "is_remote_configuration": true,
      "has_encrypted_payloads": true,
      "status": "string",
      "evaluation_runtime": "server",
      "bucketing_identifier": "distinct_id",
      "last_called_at": "2019-08-24T14:15:22Z",
      "_create_in_folder": "string",
      "_should_create_usage_dashboard": true
    }
  ]
}

Create feature flags

Required API key scopes

feature_flag:write

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Response

Example request

POST /api/projects/:project_id/feature_flags

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/projects/:project_id/feature_flags/\
	-d key="string"

Example response

Status 201

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Retrieve feature flags

This endpoint returns a feature flag and its details like name, key, variants, rollout_percentage, and more.

To evaluate and determine the value of a flag for a given user, use the flags endpoint instead.

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Response

Example request

GET /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/

Example response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Update feature flags

Required API key scopes

feature_flag:write

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Response

Example request

PATCH /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/\
	-d name="string"

Example response

Status 200

RESPONSE

{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {
    "property1": null,
    "property2": null
  },
  "deleted": true,
  "active": true,
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0,
  "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "is_simple_flag": true,
  "rollout_percentage": 0,
  "ensure_experience_continuity": true,
  "experiment_set": "string",
  "surveys": {
    "property1": null,
    "property2": null
  },
  "features": {
    "property1": null,
    "property2": null
  },
  "rollback_conditions": null,
  "performed_rollback": true,
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_tags": [
    null
  ],
  "usage_dashboard": 0,
  "analytics_dashboards": [
    0
  ],
  "has_enriched_analytics": true,
  "user_access_level": "string",
  "creation_context": "feature_flags",
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "status": "string",
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "_create_in_folder": "string",
  "_should_create_usage_dashboard": true
}

Delete feature flags

Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

Required API key scopes

feature_flag:write

Path parameters

id
integer
project_id
string

Example request

DELETE /api/projects/:project_id/feature_flags/:id

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/

Example response

Status 405 No response body

Retrieve feature flags activity retrieve

Required API key scopes

activity_log:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/activity/

Example response

Status 200 No response body

Create feature flags create static cohort for flag

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/create_static_cohort_for_flag

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/projects/:project_id/feature_flags/:id/create_static_cohort_for_flag/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags dashboard

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/dashboard

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/projects/:project_id/feature_flags/:id/dashboard/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags enrich usage dashboard

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/enrich_usage_dashboard

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/projects/:project_id/feature_flags/:id/enrich_usage_dashboard/\
	-d key="string"

Example response

Status 200 No response body

Create feature flags has active dependents

Check if this flag has other active flags that depend on it.

Path parameters

id
integer
project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/:id/has_active_dependents

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/projects/:project_id/feature_flags/:id/has_active_dependents/\
	-d key="string"

Example response

Status 200 No response body

Retrieve feature flags remote config

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/remote_config

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/remote_config/

Example response

Status 200 No response body

Retrieve feature flags status

Required API key scopes

feature_flag:read

Path parameters

id
integer
project_id
string

Example request

GET /api/projects/:project_id/feature_flags/:id/status

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/:id/status/

Example response

Status 200 No response body

Retrieve feature flags activity

Required API key scopes

activity_log:read

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/activity

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/activity/

Example response

Status 200 No response body

Create feature flags bulk keys

Get feature flag keys by IDs. Accepts a list of feature flag IDs and returns a mapping of ID to key.

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/bulk_keys

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/projects/:project_id/feature_flags/bulk_keys/\
	-d key="string"

Example response

Status 200 No response body

Retrieve feature flags evaluation reasons

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/evaluation_reasons

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/evaluation_reasons/

Example response

Status 200 No response body

Retrieve feature flags local evaluation

Required API key scopes

feature_flag:read

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/local_evaluation

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/local_evaluation/

Example response

Status 200 No response body

Retrieve feature flags my flags

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/feature_flags/my_flags

export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/feature_flags/my_flags/

Example response

Status 200 No response body

Create feature flags user blast radius

Path parameters

project_id
string

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
created_at
string
version
integer
Default: 0
ensure_experience_continuity
boolean
rollback_conditions
performed_rollback
boolean
tags
array
evaluation_tags
array
analytics_dashboards
array
has_enriched_analytics
boolean
creation_context
is_remote_configuration
boolean
has_encrypted_payloads
boolean
evaluation_runtime
bucketing_identifier
last_called_at
string
_create_in_folder
string
_should_create_usage_dashboard
boolean
Default: true

Example request

POST /api/projects/:project_id/feature_flags/user_blast_radius

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/projects/:project_id/feature_flags/user_blast_radius/\
	-d key="string"

Example response

Status 200 No response body

PostHog is an all-in-one developer platform for building successful products. We provide product analytics, web analytics, session replay, error tracking, feature flags, experiments, surveys, LLM analytics, data warehouse, CDP, and an AI product assistant to help debug your code, ship features faster, and keep all your usage and customer data in one stack.