Experiments API

Use the API when experiments need to be created or read by something other than a person – a release pipeline that opens an experiment with every feature branch, an internal dashboard that shows what's currently running, or a script that ends tests once they reach significance.

Reading requires the experiment:read scope and writing requires experiment:write, both on a personal API key.

What's available

Experiments

List, create, retrieve, update, and delete experiments under /api/projects/:project_id/experiments/. Creating an experiment also creates its backing feature flag. Lifecycle actions – launching, pausing, ending, shipping a variant, archiving, and freezing exposures – are available as sub-actions on an individual experiment, and there are endpoints for results, a results timeseries, and the change history.

Holdouts

Manage holdout groups under /api/projects/:project_id/experiment_holdouts/ so the same excluded users can be reused across experiments.

Shared metrics

Manage reusable metrics under /api/projects/:project_id/experiment_saved_metrics/.

Authentication

Pass your personal API key as a bearer token:

curl -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  https://us.posthog.com/api/projects/:project_id/experiments/

Related

• Design and analyze experiments in the web app.
• Drive the same endpoints conversationally over MCP.
• See the full PostHog API reference.