Experiments API Reference

Experiments

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

Endpoints

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

List all experiments

Required API key scopes

experiment:read

Path parameters

project_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/experiments

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/

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",
      "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_tags": [
          "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": 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": true,
      "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": null,
      "metrics": null,
      "metrics_secondary": null,
      "stats_config": null,
      "_create_in_folder": "string",
      "conclusion": "won",
      "conclusion_comment": "string",
      "primary_metrics_ordered_uuids": null,
      "secondary_metrics_ordered_uuids": null,
      "user_access_level": "string"
    }
  ]
}

Create experiments

Required API key scopes

experiment:write

Path parameters

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
deleted
boolean
type
exposure_criteria
metrics
metrics_secondary
stats_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids

Response

Example request

POST /api/projects/:project_id/experiments

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/\
	-d name="string",\
	-d feature_flag_key="string"

Example response

Status 201

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_tags": [
      "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": 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": true,
  "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": null,
  "metrics": null,
  "metrics_secondary": null,
  "stats_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "user_access_level": "string"
}

Retrieve experiments

Required API key scopes

experiment:read

Path parameters

id
integer
project_id
string

Response

Example request

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

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_tags": [
      "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": 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": true,
  "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": null,
  "metrics": null,
  "metrics_secondary": null,
  "stats_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "user_access_level": "string"
}

Update experiments

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
deleted
boolean
type
exposure_criteria
metrics
metrics_secondary
stats_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids

Response

Example request

PATCH /api/projects/:project_id/experiments/: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/experiments/:id/\
	-d name="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_tags": [
      "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": 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": true,
  "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": null,
  "metrics": null,
  "metrics_secondary": null,
  "stats_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "user_access_level": "string"
}

Delete experiments

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

Required API key scopes

experiment:write

Path parameters

id
integer
project_id
string

Example request

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

Example response

Status 405 No response body

Create experiments create exposure cohort for experiment

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
deleted
boolean
type
exposure_criteria
metrics
metrics_secondary
stats_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids

Example request

POST /api/projects/:project_id/experiments/:id/create_exposure_cohort_for_experiment

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/create_exposure_cohort_for_experiment/\
	-d name="string",\
	-d feature_flag_key="string"

Example response

Status 200 No response body

Create experiments duplicate

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
deleted
boolean
type
exposure_criteria
metrics
metrics_secondary
stats_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids

Example request

POST /api/projects/:project_id/experiments/:id/duplicate

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/duplicate/\
	-d name="string",\
	-d feature_flag_key="string"

Example response

Status 200 No response body

Create experiments recalculate timeseries

Create a recalculation request for experiment timeseries data.

Request body:

metric (required): The full metric object to recalculate
fingerprint (required): The fingerprint of the metric configuration

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
deleted
boolean
type
exposure_criteria
metrics
metrics_secondary
stats_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids

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

Retrieve experiments timeseries results

Retrieve timeseries results for a specific experiment-metric combination. Aggregates daily results into a timeseries format for frontend compatibility.

Query parameters:

metric_uuid (required): The UUID of the metric to retrieve results for
fingerprint (required): The fingerprint of the metric configuration

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_tags: Filter by presence of evaluation tags ("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

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 stats

Get experimentation velocity statistics.

Required API key scopes

experiment:read

Path parameters

project_id
string

Example request

GET /api/projects/:project_id/experiments/stats

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/stats/

Example response

Status 200 No response body

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