Experiments-2

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

Endpoints

POST
POST
POST
POST
POST
POST
POST
GET
GET
GET

Create experiments end

End a running experiment without shipping a variant.

Sets end_date to now and marks the experiment as stopped. The feature flag is NOT modified — users continue to see their assigned variants and exposure events ($feature_flag_called) continue to be recorded. However, only data up to end_date is included in experiment results.

Use this when:

  • You want to freeze the results window without changing which variant users see.
  • A variant was already shipped manually via the feature flag UI and the experiment just needs to be marked complete.

The end_date can be adjusted after ending via PATCH if it needs to be backdated (e.g. to match when the flag was actually paused).

Other options:

  • Use ship_variant to end the experiment AND roll out a single variant to 100%% of users.
  • Use pause to deactivate the flag without ending the experiment (stops variant assignment but does not freeze results).

Returns 400 if the experiment is not running.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • conclusion
  • conclusion_comment
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/end
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/experiments/:id/end/\
	-d conclusion=undefined

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments end

End a running experiment without shipping a variant.

Sets end_date to now and marks the experiment as stopped. The feature flag is NOT modified — users continue to see their assigned variants and exposure events ($feature_flag_called) continue to be recorded. However, only data up to end_date is included in experiment results.

Use this when:

  • You want to freeze the results window without changing which variant users see.
  • A variant was already shipped manually via the feature flag UI and the experiment just needs to be marked complete.

The end_date can be adjusted after ending via PATCH if it needs to be backdated (e.g. to match when the flag was actually paused).

Other options:

  • Use ship_variant to end the experiment AND roll out a single variant to 100%% of users.
  • Use pause to deactivate the flag without ending the experiment (stops variant assignment but does not freeze results).

Returns 400 if the experiment is not running.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • conclusion
  • conclusion_comment
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/end
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/experiments/:id/end/\
	-d conclusion=undefined

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments launch

Launch a draft experiment.

Validates the experiment is in draft state, activates its linked feature flag, sets start_date to the current server time, and transitions the experiment to running. Returns 400 if the experiment has already been launched or if the feature flag configuration is invalid (e.g. missing "control" variant or fewer than 2 variants).

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/launch
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/experiments/:id/launch/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments launch

Launch a draft experiment.

Validates the experiment is in draft state, activates its linked feature flag, sets start_date to the current server time, and transitions the experiment to running. Returns 400 if the experiment has already been launched or if the feature flag configuration is invalid (e.g. missing "control" variant or fewer than 2 variants).

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/launch
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/experiments/:id/launch/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments pause

Pause a running experiment.

Deactivates the linked feature flag so it is no longer returned by the /decide endpoint. Users fall back to the application default (typically the control experience), and no new exposure events are recorded (i.e. $feature_flag_called is not fired). Returns 400 if the experiment is not running or is already paused.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/pause
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/experiments/:id/pause/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments pause

Pause a running experiment.

Deactivates the linked feature flag so it is no longer returned by the /decide endpoint. Users fall back to the application default (typically the control experience), and no new exposure events are recorded (i.e. $feature_flag_called is not fired). Returns 400 if the experiment is not running or is already paused.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/pause
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/experiments/:id/pause/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments recalculate timeseries

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • name
    string
  • description
    string
  • start_date
    string
  • end_date
    string
  • feature_flag_key
    string
  • holdout_id
    integer
  • parameters
  • secondary_metrics
  • saved_metrics_ids
    array
  • filters
  • archived
    boolean
    Default: false
  • deleted
    boolean
  • type
  • exposure_criteria
  • metrics
  • metrics_secondary
  • stats_config
  • scheduling_config
  • allow_unknown_events
    boolean
    Default: false
  • _create_in_folder
    string
  • conclusion
  • conclusion_comment
    string
  • primary_metrics_ordered_uuids
  • secondary_metrics_ordered_uuids
  • only_count_matured_users
    boolean
  • update_feature_flag_params
    boolean
    Default: false

Example request

POST /api/projects/:project_id/experiments/:id/recalculate_timeseries
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/experiments/:id/recalculate_timeseries/\
	-d name="string",\
	-d feature_flag_key="string"

Example response

Status 200 No response body

Create experiments recalculate timeseries

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • name
    string
  • description
    string
  • start_date
    string
  • end_date
    string
  • feature_flag_key
    string
  • holdout_id
    integer
  • parameters
  • secondary_metrics
  • saved_metrics_ids
    array
  • filters
  • archived
    boolean
    Default: false
  • deleted
    boolean
  • type
  • exposure_criteria
  • metrics
  • metrics_secondary
  • stats_config
  • scheduling_config
  • allow_unknown_events
    boolean
    Default: false
  • _create_in_folder
    string
  • conclusion
  • conclusion_comment
    string
  • primary_metrics_ordered_uuids
  • secondary_metrics_ordered_uuids
  • only_count_matured_users
    boolean
  • update_feature_flag_params
    boolean
    Default: false

Example request

POST /api/projects/:project_id/experiments/:id/recalculate_timeseries
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/experiments/:id/recalculate_timeseries/\
	-d name="string",\
	-d feature_flag_key="string"

Example response

Status 200 No response body

Create experiments reset

Reset an experiment back to draft state.

Clears start/end dates, conclusion, and archived flag. The feature flag is left unchanged — users continue to see their assigned variants.

Previously collected events still exist but won't be included in results unless the start date is manually adjusted after re-launch.

Returns 400 if the experiment is already in draft state.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/reset
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/experiments/:id/reset/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments reset

Reset an experiment back to draft state.

Clears start/end dates, conclusion, and archived flag. The feature flag is left unchanged — users continue to see their assigned variants.

Previously collected events still exist but won't be included in results unless the start date is manually adjusted after re-launch.

Returns 400 if the experiment is already in draft state.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/reset
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/experiments/:id/reset/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments resume

Resume a paused experiment.

Reactivates the linked feature flag so it is returned by /decide again. Users are re-bucketed deterministically into the same variants they had before the pause, and exposure tracking resumes. Returns 400 if the experiment is not running or is not paused.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/resume
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/experiments/:id/resume/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments resume

Resume a paused experiment.

Reactivates the linked feature flag so it is returned by /decide again. Users are re-bucketed deterministically into the same variants they had before the pause, and exposure tracking resumes. Returns 400 if the experiment is not running or is not paused.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/resume
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/experiments/:id/resume/

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments ship variant

Ship a variant to 100% of users and (optionally) end the experiment.

Rewrites the feature flag so that the selected variant is served to everyone. Existing release conditions (flag groups) are preserved so the change can be rolled back by deleting the auto-added release condition in the feature flag UI.

Can be called on both running and stopped experiments. If the experiment is still running, it will also be ended (end_date set and status marked as stopped). If the experiment has already ended, only the flag is rewritten - this supports the "end first, ship later" workflow.

If an approval policy requires review before changes on the flag take effect, the API returns 409 with a change_request_id. The experiment is NOT ended until the change request is approved and the user retries.

Returns 400 if the experiment is in draft state, the variant_key is not found on the flag, or the experiment has no linked feature flag.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • conclusion
  • conclusion_comment
    string
  • variant_key
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/ship_variant
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/experiments/:id/ship_variant/\
	-d variant_key="string"

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments ship variant

Ship a variant to 100% of users and (optionally) end the experiment.

Rewrites the feature flag so that the selected variant is served to everyone. Existing release conditions (flag groups) are preserved so the change can be rolled back by deleting the auto-added release condition in the feature flag UI.

Can be called on both running and stopped experiments. If the experiment is still running, it will also be ended (end_date set and status marked as stopped). If the experiment has already ended, only the flag is rewritten - this supports the "end first, ship later" workflow.

If an approval policy requires review before changes on the flag take effect, the API returns 409 with a change_request_id. The experiment is NOT ended until the change request is approved and the user retries.

Returns 400 if the experiment is in draft state, the variant_key is not found on the flag, or the experiment has no linked feature flag.

Required API key scopes

experiment:write

Path parameters

  • id
    integer
  • project_id
    string

Request parameters

  • conclusion
  • conclusion_comment
    string
  • variant_key
    string

Response


Example request

POST /api/projects/:project_id/experiments/:id/ship_variant
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/experiments/:id/ship_variant/\
	-d variant_key="string"

Example response

Status 200
RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "feature_flag_key": "string",
  "feature_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "holdout": {
    "id": 0,
    "name": "string",
    "description": "string",
    "filters": null,
    "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"
  },
  "holdout_id": 0,
  "exposure_cohort": 0,
  "parameters": {
    "feature_flag_variants": null,
    "minimum_detectable_effect": null,
    "rollout_percentage": null
  },
  "secondary_metrics": null,
  "saved_metrics": [
    {
      "id": 0,
      "experiment": 0,
      "saved_metric": 0,
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "query": null,
      "name": "string"
    }
  ],
  "saved_metrics_ids": [
    null
  ],
  "filters": null,
  "archived": false,
  "deleted": 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",
  "type": "web",
  "exposure_criteria": {
    "exposure_config": {
      "event": "string",
      "kind": "ExperimentEventExposureConfig",
      "properties": [
        {
          "key": "string",
          "label": null,
          "operator": "exact",
          "type": "event",
          "value": null
        }
      ]
    },
    "filterTestAccounts": null
  },
  "metrics": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "metrics_secondary": [
    {
      "completion_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "conversion_window": null,
      "denominator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "goal": "increase",
      "kind": "ExperimentMetric",
      "metric_type": "funnel",
      "name": null,
      "numerator": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "retention_window_end": null,
      "retention_window_start": null,
      "retention_window_unit": "second",
      "series": null,
      "source": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_event": {
        "event": null,
        "id": null,
        "kind": "EventsNode",
        "properties": null
      },
      "start_handling": "first_seen",
      "uuid": null
    }
  ],
  "stats_config": null,
  "scheduling_config": null,
  "allow_unknown_events": false,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "only_count_matured_users": true,
  "update_feature_flag_params": false,
  "status": "draft",
  "user_access_level": "string"
}

Retrieve experiments timeseries results

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:read

Path parameters

  • id
    integer
  • project_id
    string

Example request

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

Example response

Status 200 No response body

Retrieve experiments timeseries results

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:read

Path parameters

  • id
    integer
  • project_id
    string

Example request

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

Example response

Status 200 No response body

Retrieve experiments eligible feature flags

Returns a paginated list of feature flags eligible for use in experiments.

Eligible flags must:

  • Be multivariate with at least 2 variants
  • Have "control" as the first variant key

Query parameters:

  • search: Filter by flag key or name (case insensitive)
  • limit: Number of results per page (default: 20)
  • offset: Pagination offset (default: 0)
  • active: Filter by active status ("true" or "false")
  • created_by_id: Filter by creator user ID
  • order: Sort order field
  • evaluation_runtime: Filter by evaluation runtime
  • has_evaluation_contexts: Filter by presence of evaluation contexts ("true" or "false")

Required API key scopes

feature_flag:read

Path parameters

  • project_id
    string

Example request

GET /api/projects/:project_id/experiments/eligible_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/experiments/eligible_feature_flags/

Example response

Status 200 No response body

Retrieve experiments eligible feature flags

Returns a paginated list of feature flags eligible for use in experiments.

Eligible flags must:

  • Be multivariate with at least 2 variants
  • Have "control" as the first variant key

Query parameters:

  • search: Filter by flag key or name (case insensitive)
  • limit: Number of results per page (default: 20)
  • offset: Pagination offset (default: 0)
  • active: Filter by active status ("true" or "false")
  • created_by_id: Filter by creator user ID
  • order: Sort order field
  • evaluation_runtime: Filter by evaluation runtime
  • has_evaluation_contexts: Filter by presence of evaluation contexts ("true" or "false")

Required API key scopes

feature_flag:read

Path parameters

  • project_id
    string

Example request

GET /api/projects/:project_id/experiments/eligible_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/experiments/eligible_feature_flags/

Example response

Status 200 No response body

Retrieve experiments requires flag implementation

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:read

Path parameters

  • project_id
    string

Example request

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

Example response

Status 200 No response body

Retrieve experiments requires flag implementation

Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.

This mixin intercepts ApprovalRequired exceptions raised by the @approval_gate decorator on serializer methods and converts them into proper HTTP 409 Conflict responses with change request details.

Required API key scopes

experiment:read

Path parameters

  • project_id
    string

Example request

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

Example response

Status 200 No response body
Next page →

Community questions

Questions about this page? or post a community question.