Experiments API Reference

Experiments

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

Endpoints

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

List all experiment holdouts

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "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"
    }
  ]
}

Create experiment holdouts

Required API key scopes

experiment:write

Path parameters

project_id
string

Request parameters

name
string
description
string
filters

Response

Example request

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

Example response

Status 201

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

Retrieve experiment holdouts

Required API key scopes

experiment:read

Path parameters

id
integer
project_id
string

Response

Example request

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

Example response

Status 200

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

Update experiment holdouts

Required API key scopes

experiment:write

Path parameters

id
integer
project_id
string

Request parameters

name
string
description
string
filters

Response

Example request

PATCH /api/projects/:project_id/experiment_holdouts/: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/experiment_holdouts/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/experiment_holdouts/{experiment_id}/".format(
        project_id=project_id,
		experiment_id="<the experiment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

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

Delete experiment holdouts

Required API key scopes

experiment:write

Path parameters

id
integer
project_id
string

Example request

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

Example response

Status 204 No response body

List all experiment saved metrics

Required API key scopes

experiment_saved_metric:read

Path parameters

project_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/experiment_saved_metrics
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/experiment_saved_metrics/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/experiment_saved_metrics/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "query": 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",
      "tags": [
        null
      ],
      "user_access_level": "string"
    }
  ]
}

Create experiment saved metrics

Required API key scopes

experiment_saved_metric:write

Path parameters

project_id
string

Request parameters

name
string
description
string
query
tags
array

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "query": 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",
  "tags": [
    null
  ],
  "user_access_level": "string"
}

Retrieve experiment saved metrics

Required API key scopes

experiment_saved_metric:read

Path parameters

id
integer
project_id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "query": 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",
  "tags": [
    null
  ],
  "user_access_level": "string"
}

Update experiment saved metrics

Required API key scopes

experiment_saved_metric:write

Path parameters

id
integer
project_id
string

Request parameters

name
string
description
string
query
tags
array

Response

Example request

PATCH /api/projects/:project_id/experiment_saved_metrics/: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/experiment_saved_metrics/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/experiment_saved_metrics/{experiment_id}/".format(
        project_id=project_id,
		experiment_id="<the experiment id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "name": "string",
  "description": "string",
  "query": 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",
  "tags": [
    null
  ],
  "user_access_level": "string"
}

Delete experiment saved metrics

Required API key scopes

experiment_saved_metric:write

Path parameters

id
integer
project_id
string

Example request

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

Example response

Status 204 No response body

List all experiments

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

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "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": 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,
      "scheduling_config": null,
      "_create_in_folder": "string",
      "conclusion": "won",
      "conclusion_comment": "string",
      "primary_metrics_ordered_uuids": null,
      "secondary_metrics_ordered_uuids": null,
      "exposure_preaggregation_enabled": true,
      "status": "draft",
      "user_access_level": "string"
    }
  ]
}

List all experiments

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

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": 0,
      "name": "string",
      "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": 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,
      "scheduling_config": null,
      "_create_in_folder": "string",
      "conclusion": "won",
      "conclusion_comment": "string",
      "primary_metrics_ordered_uuids": null,
      "secondary_metrics_ordered_uuids": null,
      "exposure_preaggregation_enabled": true,
      "status": "draft",
      "user_access_level": "string"
    }
  ]
}

Create experiments

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

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
scheduling_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids
exposure_preaggregation_enabled
boolean

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

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_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": 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,
  "scheduling_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "exposure_preaggregation_enabled": true,
  "status": "draft",
  "user_access_level": "string"
}

Create experiments

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

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
scheduling_config
_create_in_folder
string
conclusion
conclusion_comment
string
primary_metrics_ordered_uuids
secondary_metrics_ordered_uuids
exposure_preaggregation_enabled
boolean

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

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_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": 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,
  "scheduling_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "exposure_preaggregation_enabled": true,
  "status": "draft",
  "user_access_level": "string"
}

Retrieve experiments

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

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

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": 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,
  "scheduling_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "exposure_preaggregation_enabled": true,
  "status": "draft",
  "user_access_level": "string"
}

Retrieve experiments

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

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

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": 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,
  "scheduling_config": null,
  "_create_in_folder": "string",
  "conclusion": "won",
  "conclusion_comment": "string",
  "primary_metrics_ordered_uuids": null,
  "secondary_metrics_ordered_uuids": null,
  "exposure_preaggregation_enabled": true,
  "status": "draft",
  "user_access_level": "string"
}