---
title: "Start a setup run"
method: POST
path: "/api/projects/{project_id}/wizard/installs/"
tags: ["wizard"]
---

# Start a setup run

`POST /api/projects/{project_id}/wizard/installs/`

## Request

- Base URL: `https://us.posthog.com`
- URL: `https://us.posthog.com/api/projects/{project_id}/wizard/installs/`
- Auth: HTTP bearer

Start the setup agent in the cloud on a GitHub repository of this project. It adds PostHog to the code and opens a pull request. Each user can have one setup run active per project at a time.

## Path parameters

- `project_id` string, required

## Request body

- WizardInstallStartRequest
  - `repository` string, required: GitHub repository to set up, in owner/name format. The project's GitHub connection must have access to it.
  - `branch` string: Branch to start from and to open the pull request against. Defaults to the repository's default branch.
  - `idempotency_key` string: Unique key for this request. A retry with the same key returns the same run instead of starting another.

## Response `200`

A retry returned the run it already started.

- WizardInstallStart
  - `run_id` string, uuid, required: ID of the setup run. Pass it to the status endpoint.
  - `status` 'created' | 'running' | 'completed' | 'failed' | 'cancelled', required: * `created` - created * `running` - running * `completed` - completed * `failed` - failed * `cancelled` - cancelled
  - `url` string, uri, required: PostHog page where the user can follow their setup runs.

## Other responses

- `201`: The setup run started.
- `400`
- `403`
- `404`
- `409`
- `429`

## Changes

> 53 revisions in range; 1 not diffed.

- **2026-10-21** `04a392d92a14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/wizard/installs/post.md)

---

[API](https://skmtc.dev/posthog/apis/posthog-api.md) · [All operations](https://skmtc.dev/posthog/apis/posthog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/posthog/apis/posthog-api/revisions/993f70ab941b?raw)