# Experiments API - Docs

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](/docs/api.md#authentication).

## 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](/docs/feature-flags.md). 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](/docs/experiments/holdouts.md) groups under `/api/projects/:project_id/experiment_holdouts/` so the same excluded users can be reused across experiments.

**Shared metrics**

Manage reusable [metrics](/docs/experiments/metrics.md) under `/api/projects/:project_id/experiment_saved_metrics/`.

## Authentication

Pass your personal API key as a bearer token:

Terminal

PostHog AI

```bash
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](/docs/experiments/surfaces/web-app.md).
-   Drive the same endpoints conversationally over [MCP](/docs/experiments/surfaces/mcp.md).
-   See the full [PostHog API reference](/docs/api.md).

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better