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`
`GET`
`POST`
`POST`
`POST`
`GET`
`POST`
`POST`
`GET`
`POST`
`POST`

Also available via the PostHog MCP server:
feature-flag-get-all — Get 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.

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:read

Query parameters

active
string
One of: "STALE""false""true"
archived
string
One of: "false""true"
created_by_id
string
eligible_for_experiment
string
One of: "true"
evaluation_runtime
string
One of: "all""client""server"
excluded_properties
string
excluded_tags
string
has_evaluation_contexts
string
One of: "false""true"
key
string
limit
integer
offset
integer
search
string
tags
string
type
string
One of: "boolean""experiment""multivariant""remote_config"

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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": {},
      "deleted": true,
      "active": true,
      "archived": 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": {},
        "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": {},
        "role_at_organization": "engineering"
      },
      "ensure_experience_continuity": true,
      "experiment_set": [
        0
      ],
      "experiment_set_metadata": [
        {
          "id": 0,
          "name": "string",
          "is_running": true
        }
      ],
      "surveys": {},
      "features": {},
      "can_edit": true,
      "tags": [
        null
      ],
      "evaluation_contexts": [
        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",
      "is_used_in_replay_settings": true,
      "is_eligible_for_experiment": true
    }
  ]
}

Create feature flags

Also available via the PostHog MCP server:
create-feature-flag — Create feature flag

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:write

Request parameters

key
string
name
string
filters
active
boolean
archived
boolean
tags
array
evaluation_contexts
array
is_remote_configuration
boolean | null
ensure_experience_continuity
boolean | null
evaluation_runtime
bucketing_identifier

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Retrieve feature flags

Also available via the PostHog MCP server:
feature-flag-get-definition — Get feature flag definition

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.

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:read

Path parameters

id
integer

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Update feature flags

Also available via the PostHog MCP server:
update-feature-flag — Update feature flag

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Request parameters

key
string
name
string
filters
active
boolean
archived
boolean
tags
array
evaluation_contexts
array
is_remote_configuration
boolean | null
ensure_experience_continuity
boolean | null
evaluation_runtime
bucketing_identifier

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 key="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Delete feature flags

Also available via the PostHog MCP server:
delete-feature-flag — Delete feature flag

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

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 405 No response body

Retrieve feature flags activity

Also available via the PostHog MCP server:
feature-flags-activity-retrieve — Get feature flag activity log

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

activity_log:read

Path parameters

id
integer

Query parameters

limit
integer
Default: 10
page
integer
Default: 1

Response

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/activity/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "user": {},
      "activity": "string",
      "scope": "string",
      "item_id": "string",
      "detail": {
        "id": "string",
        "changes": [
          {
            "type": "string",
            "action": "string",
            "field": "string",
            "before": null,
            "after": null
          }
        ],
        "merge": {
          "type": "string",
          "source": null,
          "target": null
        },
        "trigger": {
          "job_type": "string",
          "job_id": "string",
          "payload": null
        },
        "name": "string",
        "short_id": "string",
        "type": "string"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "is_system": true,
      "was_impersonated": true,
      "client": "string"
    }
  ],
  "next": "http://example.com",
  "previous": "http://example.com",
  "total_count": 0
}

Status 404 No response body

Create feature flags archive

Archive a feature flag, hiding it from the default flag list.

Sets archived to true. An archived flag must be disabled, so an enabled flag also gets active set to false in the same write. Targeting, variants and payloads are left as they are, and linked experiment and survey history is preserved. Archiving an enabled flag is refused when other active flags depend on it. An already-archived flag is returned unchanged.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/archive
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/archive/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/archive/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted. The change matches more than one approval policy. The flag is enabled and another active flag depends on it.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Status 409 An approval policy gates this change. A change request was opened, or an open one was returned if the same action was already pending; the flag is unchanged.

RESPONSE
{
  "code": "string",
  "status": "string",
  "detail": "string",
  "message": "string",
  "resource_type": "string",
  "resource_id": "string",
  "change_request_id": "string",
  "change_request": null,
  "required_approvers": null
}

Create feature flags create static cohort for flag

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Path parameters

id
integer

Request parameters

name
string
key
string
filters
object
deleted
boolean
active
boolean
archived
boolean
version
integer
Default: 0
ensure_experience_continuity
boolean | null
tags
array
evaluation_contexts
array
analytics_dashboards
array
has_enriched_analytics
boolean | null
creation_context
is_remote_configuration
boolean | null
has_encrypted_payloads
boolean | null
evaluation_runtime
bucketing_identifier
_create_in_folder
string

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/create_static_cohort_for_flag/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

Create feature flags dashboard

Deprecated. Ensures a saved usage dashboard exists for a feature flag. This endpoint will be removed after September 25, 2026; usage charts remain available on the feature flag Usage tab.

Path parameters

id
integer

Response

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/dashboard/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "success": true
}

Status 400

RESPONSE
{
  "success": true,
  "error": "string"
}

List all feature flags dependent flags

Get other active flags that depend on this flag.

Required API key scopes

feature_flag:read

Path parameters

id
integer

Example request

GET /api/projects/:project_id/feature_flags/:id/dependent_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/:id/dependent_flags/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/dependent_flags/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "key": "string",
  "name": "string"
}

Create feature flags disable

Disable a feature flag.

Sets active to false and changes nothing else. Targeting, variants, payloads, tags and archived state are left as they are. Refused when other active flags depend on this one. An already-disabled flag is returned unchanged.

A disabled flag stops evaluating for every consumer, including a linked experiment or a session replay setting. Read the full definition first to report that impact.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/disable
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/disable/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/disable/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted. The change matches more than one approval policy. Another active flag depends on this one.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Status 409 An approval policy gates this change. A change request was opened, or an open one was returned if the same action was already pending; the flag is unchanged.

RESPONSE
{
  "code": "string",
  "status": "string",
  "detail": "string",
  "message": "string",
  "resource_type": "string",
  "resource_id": "string",
  "change_request_id": "string",
  "change_request": null,
  "required_approvers": null
}

Create feature flags enable

Enable a feature flag.

Sets active to true and changes nothing else. Targeting, variants, payloads, tags and archived state are left as they are. An archived flag is refused: unarchive it first. A flag whose own flag dependencies are disabled or use an unsupported configuration format is also refused. An already-enabled flag is returned unchanged.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/enable
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/enable/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/enable/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted. The change matches more than one approval policy. The flag is archived, one of the flags it depends on is disabled, or a flag it depends on uses an unsupported configuration format.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Status 409 An approval policy gates this change. A change request was opened, or an open one was returned if the same action was already pending; the flag is unchanged.

RESPONSE
{
  "code": "string",
  "status": "string",
  "detail": "string",
  "message": "string",
  "resource_type": "string",
  "resource_id": "string",
  "change_request_id": "string",
  "change_request": null,
  "required_approvers": null
}

Create feature flags enrich usage dashboard

Deprecated. Adds enriched insights to an existing legacy feature flag usage dashboard. No removal date has been set; usage charts remain available on the feature flag Usage tab.

Path parameters

id
integer

Response

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/enrich_usage_dashboard/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "success": true
}

Status 400

RESPONSE
{
  "success": true,
  "error": "string"
}

Retrieve feature flags remote config

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:read

Path parameters

id
integer

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/remote_config/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create feature flags roll out to everyone

Serve a feature flag to every user.

Adds a release condition with no property filters at 100% and keeps the existing conditions below it. Payloads, holdout and every other field are left as they are. On a boolean flag, removing the new condition restores the previous targeting. On a multivariate flag the variant distribution is rewritten as well, so removing the condition restores the audience but not the old split. A flag that already leads with such a condition gains no second one.

This changes targeting only. A disabled flag still serves nobody, and a holdout is evaluated before release conditions, so users in one keep getting the holdout variant instead of the rollout. A flag gated on early access enrollment is refused, because that gate is evaluated before release conditions too and no targeting change gets past it.

A multivariate flag needs variant_key, and every other flag rejects it. A release condition decides who the flag serves, not which variant they get, so rolling a multivariate flag out to everyone also gives the named variant 100% of the variant distribution and every other variant 0%. To serve everyone and keep the current split between variants, update the flag instead.

Send the version your last read returned. A change to the flag after that version is refused with 409. Read the flag again and decide the rollout against its current definition.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Request parameters

version
integer | null
variant_key
string | null

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/roll_out_to_everyone
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/roll_out_to_everyone/\
	-d version="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/roll_out_to_everyone/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"version": "integer"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted. The change matches more than one approval policy. The flag is gated on early access enrollment, a multivariate flag was sent no variant, or the variant is not one this flag defines.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Status 409 The flag changed after the version you sent. Nothing was written. Read the flag again and decide the change against its current definition. An approval policy gates this change. A change request was opened, or an open one was returned if the same action was already pending; the flag is unchanged.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Create feature flags set release condition rollout

Set what percentage of one release condition's audience a feature flag is served to.

Changes rollout_percentage on the release condition at condition_index and nothing else. The condition's property filters, every other condition, the variants, payloads, holdout and every remaining field are left as they are.

Send the version your last read returned. A change to the flag after that version is refused with 409, because a condition index only names the condition you read. Read the flag again and decide the percentage against its current definition.

On a multivariate flag this sets how many of the matching users get a variant at all. It does not change how the variants are split between them.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Request parameters

condition_index
integer
rollout_percentage
number
version
integer | null

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/set_release_condition_rollout
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/set_release_condition_rollout/\
	-d condition_index="integer",\
	-d rollout_percentage="number",\
	-d version="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/set_release_condition_rollout/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"condition_index": "integer",
		"rollout_percentage": "number",
		"version": "integer"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted. The change matches more than one approval policy. It has no release condition at that index.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Status 409 The flag changed after the version you sent. Nothing was written. Read the flag again and decide the change against its current definition. An approval policy gates this change. A change request was opened, or an open one was returned if the same action was already pending; the flag is unchanged.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}

Retrieve feature flags status

Also available via the PostHog MCP server:
feature-flags-status-retrieve — Get feature flag status

Create, read, update and delete feature flags. See docs for more information on feature flags.

If you're looking to use feature flags on your application, you can either use our JavaScript Library or our dedicated endpoint to check if feature flags are enabled for a given user.

Required API key scopes

feature_flag:read

Path parameters

id
integer

Response

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/status/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "status": "string",
  "reason": "string",
  "reason_states_rollout": true,
  "rollout": {
    "effectively_full_rollout": true,
    "has_targeting_conditions": true,
    "max_rollout_percentage": 0,
    "is_multivariate": true
  }
}

Create feature flags test evaluation

Also available via the PostHog MCP server:
feature-flags-test-evaluation-create — Test feature flag evaluation

Test feature flag evaluation against a specific user at an optional point in time.

This endpoint allows testing how a feature flag would evaluate for a specific user, optionally at a historical timestamp. When a timestamp is provided, both the flag conditions and person properties are evaluated as they existed at that time.

Required API key scopes

feature_flag:read

Path parameters

id
integer

Request parameters

distinct_id
string
person_id
string
timestamp
string | null
groups

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/test_evaluation
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/test_evaluation/\
	-d distinct_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/test_evaluation/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"distinct_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "flag_key": "string",
  "result": null,
  "reason": "string",
  "reason_description": "string",
  "condition_index": 0,
  "payload": null,
  "person_properties": {},
  "evaluation_distinct_id": "string",
  "conditions": [
    {
      "index": 0,
      "matched": true,
      "properties_matched": true,
      "explanation": "string",
      "rollout_percentage": 0.1,
      "rollout_excluded": true,
      "variant": "string",
      "properties": [
        {
          "key": "string",
          "operator": "string",
          "value": null,
          "type": "string",
          "actual_value": null,
          "matched": true,
          "explanation": "string"
        }
      ]
    }
  ]
}

Status 400 Invalid parameters

RESPONSE
{
  "error": "string"
}

Status 404 Person not found

RESPONSE
{
  "error": "string"
}

Status 500 Server error

RESPONSE
{
  "error": "string"
}

Status 502 Flag evaluation service error

RESPONSE
{
  "error": "string"
}

Status 503 Person lookup service unavailable

RESPONSE
{
  "error": "string"
}

Create feature flags unarchive

Restore an archived feature flag to the default flag list.

Sets archived to false and changes nothing else. The flag stays disabled; enable it with a separate call. An already-unarchived flag is returned unchanged.

Required API key scopes

feature_flag:write

Path parameters

id
integer

Response

Example request

POST /api/projects/:project_id/feature_flags/:id/unarchive
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/unarchive/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/{feature_flag_id}/unarchive/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "key": "string",
  "filters": {},
  "deleted": true,
  "active": true,
  "archived": 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": {},
    "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": {},
    "role_at_organization": "engineering"
  },
  "ensure_experience_continuity": true,
  "experiment_set": [
    0
  ],
  "experiment_set_metadata": [
    {
      "id": 0,
      "name": "string",
      "is_running": true
    }
  ],
  "surveys": {},
  "features": {},
  "can_edit": true,
  "tags": [
    null
  ],
  "evaluation_contexts": [
    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",
  "is_used_in_replay_settings": true,
  "is_eligible_for_experiment": true
}

Status 400 The flag is deleted.

RESPONSE
{
  "type": "string",
  "code": "string",
  "detail": "string",
  "attr": "string"
}