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

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"
created_by_id
string
evaluation_runtime
string
One of: "both""client""server"
excluded_properties
string
has_evaluation_contexts
string
One of: "false""true"
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,
      "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": [
        {}
      ],
      "surveys": {},
      "features": {},
      "rollback_conditions": null,
      "performed_rollback": true,
      "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",
      "_should_create_usage_dashboard": true,
      "is_used_in_replay_settings": 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
tags
array
evaluation_contexts
array

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,
  "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": [
    {}
  ],
  "surveys": {},
  "features": {},
  "rollback_conditions": null,
  "performed_rollback": true,
  "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",
  "_should_create_usage_dashboard": true,
  "is_used_in_replay_settings": 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,
  "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": [
    {}
  ],
  "surveys": {},
  "features": {},
  "rollback_conditions": null,
  "performed_rollback": true,
  "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",
  "_should_create_usage_dashboard": true,
  "is_used_in_replay_settings": 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
tags
array
evaluation_contexts
array

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,
  "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": [
    {}
  ],
  "surveys": {},
  "features": {},
  "rollback_conditions": null,
  "performed_rollback": true,
  "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",
  "_should_create_usage_dashboard": true,
  "is_used_in_replay_settings": 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"
    }
  ],
  "next": "http://example.com",
  "previous": "http://example.com",
  "total_count": 0
}

Status 404 No response body

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
created_at
string
version
integer
Default: 0
ensure_experience_continuity
booleannull
rollback_conditions
performed_rollback
booleannull
tags
array
evaluation_contexts
array
analytics_dashboards
array
has_enriched_analytics
booleannull
creation_context
is_remote_configuration
booleannull
has_encrypted_payloads
booleannull
evaluation_runtime
bucketing_identifier
last_called_at
stringnull
_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"
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

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
created_at
string
version
integer
Default: 0
ensure_experience_continuity
booleannull
rollback_conditions
performed_rollback
booleannull
tags
array
evaluation_contexts
array
analytics_dashboards
array
has_enriched_analytics
booleannull
creation_context
is_remote_configuration
booleannull
has_encrypted_payloads
booleannull
evaluation_runtime
bucketing_identifier
last_called_at
stringnull
_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"
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)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

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 enrich usage dashboard

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
created_at
string
version
integer
Default: 0
ensure_experience_continuity
booleannull
rollback_conditions
performed_rollback
booleannull
tags
array
evaluation_contexts
array
analytics_dashboards
array
has_enriched_analytics
booleannull
creation_context
is_remote_configuration
booleannull
has_encrypted_payloads
booleannull
evaluation_runtime
bucketing_identifier
last_called_at
stringnull
_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"
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)},
	data={
		"key": "string"
	}
).json()

Example response

Status 200 No response body

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

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"
}

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
stringnull
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",
  "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"
}

Retrieve feature flags versions

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
version_number
integer

Response

Example request

GET /api/projects/:project_id/feature_flags/:id/versions/:version_number
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/versions/:version_number/
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}/versions/{version_number}/".format(
        project_id=project_id,
		feature_flag_id="<the feature flag id>",
		version_number="<the version number>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "key": "string",
  "name": "string",
  "filters": {},
  "active": true,
  "deleted": true,
  "version": -2147483648,
  "rollback_conditions": null,
  "performed_rollback": true,
  "ensure_experience_continuity": true,
  "has_enriched_analytics": true,
  "is_remote_configuration": true,
  "has_encrypted_payloads": true,
  "evaluation_runtime": "server",
  "bucketing_identifier": "distinct_id",
  "last_called_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": 0,
  "is_historical": true,
  "version_timestamp": "2019-08-24T14:15:22Z",
  "modified_by": 0
}

Status 400 Version history is not available for remote configuration flags.

Status 404 Version not found.

Status 422 Activity log incomplete; cannot reconstruct this version.

Retrieve feature flags all activity

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

Query parameters

limit
integer
Default: 10
page
integer
Default: 1

Response

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/activity/".format(
        project_id=project_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"
    }
  ],
  "next": "http://example.com",
  "previous": "http://example.com",
  "total_count": 0
}

Create feature flags bulk delete

Bulk delete feature flags by filter criteria or explicit IDs.

Accepts either:

{"filters": {...}} - Same filter params as list endpoint (search, active, type, etc.)
{"ids": [...]} - Explicit list of flag IDs (no limit)

Returns same format as bulk_delete for UI compatibility.

Uses bulk operations for efficiency: database updates are batched and cache invalidation happens once at the end rather than per-flag.

Required API key scopes

feature_flag:write

Request parameters

filters
ids
array

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "deleted": [
    {
      "id": 0,
      "key": "string",
      "rollout_state": "fully_rolled_out",
      "active_variant": "string"
    }
  ],
  "errors": [
    {
      "id": null,
      "key": "string",
      "reason": "string"
    }
  ]
}

Status 400 Invalid input — e.g., both filters and ids supplied, neither supplied, or unknown filter keys.

RESPONSE
{
  "error": "string"
}

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.

Required API key scopes

feature_flag:read

Request parameters

ids
array

Response

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

Example response

Status 200

RESPONSE
{
  "keys": {
    "property1": "string",
    "property2": "string"
  },
  "warning": "string"
}

Status 400 Invalid flag IDs provided.

RESPONSE
{
  "error": "string"
}

Create feature flags bulk update tags

Bulk update tags on multiple objects.

PAT access: this action has no required_scopes= on the decorator — inheriting viewsets must add "bulk_update_tags" to their scope_object_write_actions list to accept personal API keys. Without that opt-in, APIScopePermission rejects PAT requests with "This action does not support personal API key access". Done per-viewset so granting <scope>:write for one resource doesn't leak access to sibling resources that share this mixin.

Accepts:

{"ids": [...], "action": "add"|"remove"|"set", "tags": ["tag1", "tag2"]}

Actions:

"add": Add tags to existing tags on each object
"remove": Remove specific tags from each object
"set": Replace all tags on each object with the provided list

Required API key scopes

feature_flag:write

Request parameters

ids
array
action
tags
array

Response

Example request

POST /api/projects/:project_id/feature_flags/bulk_update_tags
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_update_tags/\
	-d ids="array",\
	-d action=undefined,\
	-d tags="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/feature_flags/bulk_update_tags/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array",
		"tags": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "updated": [
    {
      "id": 0,
      "tags": [
        "string"
      ]
    }
  ],
  "skipped": [
    {
      "id": 0,
      "reason": "string"
    }
  ]
}

Retrieve feature flags evaluation reasons

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

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

distinct_id
string
groups
string
Default: {}

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