PostHog

https://posthog.com/docs
Admin
PostHog is an open-source platform for product analytics, feature flags, session recording, and data...
Tokens:6,193,072
Snippets:39,488
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Status 201 The setup task that started

Source: https://posthog.com/docs/api/task-channels

Example response body for a successful (201) setup request. Contains the `task_id` of the started setup task.

```json
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}
```

--------------------------------

### Retrieve users two factor start setup - cURL and Python examples

Source: https://posthog.com/docs/api/users-4

Example request for the GET /api/users/:uuid/two_factor_start_setup endpoint. The cURL command uses a personal API key exported as POSTHOG_PERSONAL_API_KEY. The Python example uses the requests library and expects a project_id and uuid. The response is a 200 status with no response body.

```bash
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/two_factor_start_setup/

```

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/two_factor_start_setup/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

```

--------------------------------

### Example response for install info

Source: https://posthog.com/docs/api/stamphog

Example JSON response for the install info endpoint. Shows the structure with `app_slug`, `install_url`, and `authorize_url` fields.

```json
{
  "app_slug": "string",
  "install_url": "string",
  "authorize_url": "string"
}
```

--------------------------------

### Python: Retrieve users start 2FA setup

Source: https://posthog.com/docs/api/users-4

Python requests example to start 2FA setup for a user. Uses a personal API key and uuid path parameter. Returns a JSON response with status 200 and no body.

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/start_2fa_setup/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()
```

--------------------------------

### start

Source: https://posthog.com/docs/references/posthog-react-native/types/PostHogReactNativePluginExtended

Legacy session replay setup entrypoint. Prefer setup() for new native features.

```APIDOC
## start

### Description
Legacy session replay setup entrypoint. Prefer setup() for new native features.

### Method
start

### Signature
`(sessionId: string, sdkOptions: PostHogReactNativePluginMap, sdkReplayConfig: PostHogReactNativePluginMap, decideReplayConfig: PostHogReactNativePluginMap) => Promise<void>`

### Parameters
- **sessionId** (string) - Required - The session identifier.
- **sdkOptions** (PostHogReactNativePluginMap) - Required - SDK options.
- **sdkReplayConfig** (PostHogReactNativePluginMap) - Required - SDK replay configuration.
- **decideReplayConfig** (PostHogReactNativePluginMap) - Required - Decide replay configuration.

### Returns
Promise<void>
```

--------------------------------

### GET MCP server installation - Example response (status 200)

Source: https://posthog.com/docs/api/mcp-server-installations

Example response body for a successful GET request (status 200). Shows the structure of an MCP server installation object, including fields like `id`, `template_id`, `name`, `auth_type`, `is_enabled`, and timestamps.

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  "name": "string",
  "icon_key": "",
  "icon_domain": "",
  "display_name": "string",
  "url": "http://example.com",
  "description": "string",
  "auth_type": "api_key",
  "is_enabled": true,
  "scope": "personal",
  "is_owner": true,
  "needs_reauth": true,
  "pending_oauth": true,
  "proxy_url": "string",
  "tool_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
```

--------------------------------

### Example response for GitHub install requests

Source: https://posthog.com/docs/api/users-3

Example response body for the GET /api/users/:uuid/integrations/github/install_requests/ endpoint with status 200. Shows the list of install-approval requests, each with an id, github_login, status (e.g., pending), installation_id, account_login, account_type, requested_at, and resolved_at, plus an install_url.

```json
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "github_login": "string",
      "status": "pending",
      "installation_id": "string",
      "account_login": "string",
      "account_type": "string",
      "requested_at": "2019-08-24T14:15:22Z",
      "resolved_at": "2019-08-24T14:15:22Z"
    }
  ],
  "install_url": "string"
}

```

--------------------------------

### Install PostHog Go SDK

Source: https://posthog.com/docs/error-tracking/installation/go

Install the PostHog Go SDK using the go get command.

```bash
go get github.com/posthog/posthog-go
```

--------------------------------

### Run Codex and install PostHog plugin

Source: https://posthog.com/docs/model-context-protocol/codex

Starts Codex and instructs the user to run /plugins, select PostHog, and install it.

```bash
codex
# Then run /plugins, select PostHog, and install
```

--------------------------------

### Web: Setup PostHog with no-argument PostHogContext

Source: https://posthog.com/docs/libraries/kmp

On the web, use the no-argument PostHogContext() when calling PostHog.setup. This example shows setup in the main function.

```Kotlin
// main.kt
fun main() {
    PostHog.setup(
        config = PostHogConfig(apiKey = "<ph_project_token>"),
        context = PostHogContext(),
    )
}

```

--------------------------------

### Install PostHog Go library with go get

Source: https://posthog.com/docs/product-analytics/installation/go

Run this command in your terminal to install the PostHog Go library.

```bash
go get "github.com/posthog/posthog-go"
```

--------------------------------

### JVM (desktop): Setup PostHog with no-argument PostHogContext

Source: https://posthog.com/docs/libraries/kmp

On the JVM (e.g., Compose Multiplatform desktop app), use the no-argument PostHogContext() when calling PostHog.setup. This example shows setup in the main function with a Window.

```Kotlin
// main.kt
fun main() = application {
    PostHog.setup(
        config = PostHogConfig(apiKey = "<ph_project_token>"),
        context = PostHogContext(),
    )
    Window(onCloseRequest = ::exitApplication) { App() }
}

```

--------------------------------

### Python requests for setup_plan

Source: https://posthog.com/docs/api/marketing-analytics

Python example using the requests library to call the setup_plan endpoint. Requires a personal API key with the marketing_analytics:read scope. Replace <ph_app_host> and project_id with your actual values.

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/setup_plan/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()
```

--------------------------------

### Example response for sync_installation (Status 200)

Source: https://posthog.com/docs/api/stamphog

Shows the JSON response body returned on success. Contains synced repository configurations, skipped entries, available count, app installation status, and installation details.

```json
{
  "synced": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "provider": "string",
      "repository": "string",
      "enabled": true,
      "installation_id": "string",
      "digest_enabled": true,
      "review_mode": "all",
      "trigger_label": "string",
      "user_access_level": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skipped": [
    "string"
  ],
  "available_count": 0,
  "app_not_installed": true,
  "installations": [
    {
      "id": "string",
      "account_login": "string"
    }
  ]
}
```

--------------------------------

### GET /api/users/:uuid/two_factor_start_setup

Source: https://posthog.com/docs/api/users-4

Starts the two-factor authentication setup process for a user. This endpoint is used to initiate the setup flow.

```APIDOC
## [GET] /api/users/:uuid/two_factor_start_setup

### Description
Starts the two-factor authentication setup process for a user. This endpoint is used to initiate the setup flow.

### Method
GET

### Endpoint
/api/users/:uuid/two_factor_start_setup

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the user.

### Request Example
```
curl -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" <ph_app_host>/api/users/:uuid/two_factor_start_setup/
```

### Response
#### Success Response (200)
No response body.

```

--------------------------------

### Example response for POST /api/users/:uuid/integrations/slack/start

Source: https://posthog.com/docs/api/users-3

Example response body for a successful (200) request. Contains the install_url string.

```json
{
  "install_url": "string"
}

```

--------------------------------

### setup()

Source: https://posthog.com/docs/references/posthog-python

Creates or returns the global PostHog client configured by module settings. Called automatically by global APIs such as `capture()`.

```APIDOC
## setup()

### Description
Create or return the global PostHog client configured by module settings. Most applications should either instantiate `Posthog` directly or set `posthog.api_key`/other module settings before calling top-level helpers. `setup()` is called automatically by global APIs such as `capture()`.

### Method
Function call

### Endpoint
`setup()`

### Parameters
None

### Returns
- **Client** - The global `Client` instance. If both `api_key` and `project_api_key` are missing or blank, the client is disabled and module-level calls become no-ops.
```

--------------------------------

### GET /api/users/:uuid/start_2fa_setup

Source: https://posthog.com/docs/api/users-4

Retrieves the user's 2FA setup start information.

```APIDOC
## [GET] /api/users/:uuid/start_2fa_setup

### Description
Retrieves the user's 2FA setup start information.

### Method
GET

### Endpoint
/api/users/:uuid/start_2fa_setup

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The UUID of the user.

### Request Example
```
GET /api/users/:uuid/start_2fa_setup
```

### Response
#### Success Response (200)
No response body.

```

--------------------------------

### setup

Source: https://posthog.com/docs/references/posthog-react-native/types/PostHogReactNativePluginExtended

Sets up the plugin with a session ID and SDK options. This is the preferred entry point for new native features.

```APIDOC
## setup

### Description
Sets up the plugin with a session ID and SDK options. This is the preferred entry point for new native features.

### Method
setup

### Signature
`(sessionId: string, sdkOptions: PostHogReactNativePluginMap, pluginConfig?: PostHogReactNativePluginConfig) => Promise<void>`

### Parameters
- **sessionId** (string) - Required - The session identifier.
- **sdkOptions** (PostHogReactNativePluginMap) - Required - SDK options for the plugin.
- **pluginConfig** (PostHogReactNativePluginConfig) - Optional - Plugin configuration.

### Returns
Promise<void>
```

--------------------------------

### GET /api/projects/:project_id/mcp_server_installations/authorize

Source: https://posthog.com/docs/api/mcp-server-installations

Starts or restarts an OAuth flow for MCP server installations. Use template_id to connect a catalog template or installation_id to reconnect an existing custom install.

```APIDOC
## GET /api/projects/:project_id/mcp_server_installations/authorize

### Description
Start (or re-start) an OAuth flow. Pass `template_id` to (re)connect a catalog template, or `installation_id` to reconnect an existing custom install using its cached metadata and per-user DCR creds.

### Method
GET

### Endpoint
/api/projects/:project_id/mcp_server_installations/authorize

### Parameters
#### Query Parameters
- **install_source** (string) - Optional - Default: `posthog`. One of: `"posthog"`, `"posthog-code"`.
- **installation_id** (string) - Optional - Description not provided.
- **posthog_code_callback_url** (string) - Optional - Default: ``.
- **return_path** (string) - Optional - Default: ``.
- **template_id** (string) - Optional - Description not provided.

### Required API Key Scopes
`project:read`

### Request Example
```
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_server_installations/authorize/
```

### Response
#### Success Response (200)
No response body.

```

--------------------------------

### List business knowledge playground chats (GET /api/projects/:project_id/business_knowledge/playground/chats)

Source: https://posthog.com/docs/api/business-knowledge

Lists all business knowledge playground chats started by the current user. Requires the `business_knowledge:read` API key scope. The cURL example sets the personal API key as an environment variable and sends a GET request; the Python example uses the `requests` library to perform the same GET request and parse the JSON response.

```bash
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/business_knowledge/playground/chats/
```

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/business_knowledge/playground/chats/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()
```

--------------------------------

### Example response for apply_setup_ops

Source: https://posthog.com/docs/api/marketing-analytics

Example response body for a successful apply_setup_ops request. Contains the applied operations, the undo operations, and the marketing analytics configuration.

```json
{
  "applied": [
    null
  ],
  "undo_ops": [
    null
  ],
  "marketing_analytics_config": null
}

```

--------------------------------

### Retrieve GitHub install requests (cURL and Python)

Source: https://posthog.com/docs/api/users-3

Example request for the GET /api/users/:uuid/integrations/github/install_requests/ endpoint. Requires a personal API key with the user:read scope. The cURL example sets the key as an environment variable and passes it in the Authorization header; the Python example uses the requests library and formats the UUID into the URL.

```bash
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/users/:uuid/integrations/github/install_requests/

```

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/users/{uuid}/integrations/github/install_requests/".format(
        project_id=project_id,
		uuid="<the uuid>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

```

--------------------------------

### PostHogSDK.setup

Source: https://posthog.com/docs/references/posthog-ios

Initializes the PostHog SDK with the provided configuration.

```APIDOC
## PostHogSDK.setup

### Description
Initializes the PostHog SDK with the provided configuration.

### Method
setup

### Parameters
- **config** (PostHogConfig) - Required - The configuration object.

### Request Example
```swift
PostHogSDK.shared.setup(config: "config_value")
```

### Response
- **Void** - No return value.
```

--------------------------------

### Authorize MCP server installation - cURL and Python examples

Source: https://posthog.com/docs/api/mcp-server-installations

Example request for the authorize endpoint. The cURL command sets the personal API key and sends a GET request; the Python snippet uses the requests library to perform the same call and parse the JSON response.

```bash
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/mcp_server_installations/authorize/

```

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/mcp_server_installations/authorize/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

```

--------------------------------

### POST /api/projects/:project_id/marketing_analytics/apply_setup_ops/

Source: https://posthog.com/docs/api/marketing-analytics

Documentation for the POST endpoint that applies setup operations atomically.

```APIDOC
## POST /api/projects/:project_id/marketing_analytics/apply_setup_ops/

### Description
Apply one or more setup operations from the setup plan, atomically. Either every operation lands or none does — a partially-applied batch has no well-defined undo. Returns `undo_ops`, computed from the pre-change state, which can be POSTed back to reverse the batch. Only send `apply` payloads returned by setup_plan.

### Method
POST

### Endpoint
/api/projects/:project_id/marketing_analytics/apply_setup_ops/

### Parameters
#### Request Body
- **ops** (array) - Required - The setup operations to apply.
- **source** (string) - Optional - Default: `setup_tab`

### Request Example
```
POST /api/projects/:project_id/marketing_analytics/apply_setup_ops/
Content-Type: application/json
Authorization: Bearer $POSTHOG_PERSONAL_API_KEY

{
  "ops": "array"
}
```

### Response
#### Success Response (200)
- **applied** (array) - The applied operations.
- **undo_ops** (array) - The ops that reverse the applied operations.
- **marketing_analytics_config** (object) - The updated marketing analytics configuration.

#### Response Example
```
{
  "applied": [
    null
  ],
  "undo_ops": [
    null
  ],
  "marketing_analytics_config": null
}
```

#### Error Responses
- **400** - An operation was malformed, unsupported, or not applicable.
- **404** - Marketing Setup and new dashboard feature flags are both off.

### Authentication
Requires API key scope: `marketing_analytics:write`
```

--------------------------------

### Update CLI to get api command

Source: https://posthog.com/docs/cli

If the 'api' command is unavailable, your CLI version is too old. Reinstall the latest version using your installation method, for example with npm, then rerun the command.

```bash
npm install -g @posthog/cli@latest
posthog-cli api --agent-help
```

--------------------------------

### Retrieve marketing analytics UTM audit - GET request examples

Source: https://posthog.com/docs/api/marketing-analytics

Example request for GET /api/projects/:project_id/marketing_analytics/utm_audit. The cURL example uses the POSTHOG_PERSONAL_API_KEY environment variable and sends a GET request. The Python example uses the requests library to GET and parse the JSON response. Requires the marketing_analytics:read API key scope.

```bash
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/utm_audit/

```

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/utm_audit/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

```

--------------------------------

### POST /api/projects/:project_id/task_channels/:id/setup

Source: https://posthog.com/docs/api/task-channels

Starts the setup process for a task channel. Requires multiple scopes including task:write and canvas:write.

```APIDOC
## POST /api/projects/:project_id/task_channels/:id/setup

### Description
Starts one unattended task in the channel that resolves the metric, writes the context page and, for a goal, creates the tracking canvas and the loops. The task becomes the channel's context generation task.

### Method
POST

### Endpoint
/api/projects/:project_id/task_channels/:id/setup

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the task channel.

#### Request Body
- **kind** (string) - Required - The kind of setup.
- **goal** (string) - Required - The goal for the setup.
- **feature** (string) - Required - The feature for the setup.
- **repository** (string | null) - Optional - The repository for the setup.

### Request Example
```
POST /api/projects/:project_id/task_channels/:id/setup
Content-Type: application/json

{
  "kind": "undefined",
  "goal": "string",
  "feature": "string",
  "repository": null
}
```

### Response
#### Success Response (201)
- **task_id** (string) - The ID of the started setup task.

#### Response Example
```
{
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}
```

#### Error Response (409)
- **detail** (string) - Error detail.
- **error** (string) - Error message.
- **type** (string) - Error type.
- **code** (string) - Error code.
- **retry_token** (string) - Retry token.
- **reason** (string) - Reason for the error.
- **attr** (string) - Attribute causing the error.
- **missing_artifact_ids** (array of strings) - Missing artifact IDs.
- **limit_type** (string) - Limit type.
- **reset_at** (string) - Reset timestamp.
- **is_pro** (boolean) - Whether the error is pro.

#### Error Response (503)
- **detail** (string) - Error detail.
- **error** (string) - Error message.
- **type** (string) - Error type.
- **code** (string) - Error code.
- **retry_token** (string) - Retry token.
- **reason** (string) - Reason for the error.
- **attr** (string) - Attribute causing the error.
- **missing_artifact_ids** (array of strings) - Missing artifact IDs.
- **limit_type** (string) - Limit type.
- **reset_at** (string) - Reset timestamp.
- **is_pro** (boolean) - Whether the error is pro.
```

--------------------------------

### Python requests to retrieve webhook URL

Source: https://posthog.com/docs/api/messaging-preferences

Python requests example for the webhook_url endpoint. Returns the webhook URL for Customer.io integration setup. Sends a GET request and parses the JSON response.

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/messaging_preferences/webhook_url/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

```

--------------------------------

### Example response for link existing GitHub installation

Source: https://posthog.com/docs/api/integrations-2

Example JSON response with status 200. Shows the structure of the created integration object, including fields like `id`, `kind`, `config`, `created_at`, `created_by`, `errors`, `display_name`, `files_write_requestable`, `installation_shared`, and `installation_status`.

```json
{
  "id": 0,
  "kind": "anthropic",
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "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": {},
    "role_at_organization": "engineering"
  },
  "errors": "string",
  "display_name": "string",
  "files_write_requestable": true,
  "installation_shared": true,
  "installation_status": "connected"
}

```

--------------------------------

### Python requests to apply setup ops

Source: https://posthog.com/docs/api/marketing-analytics

Python example using the `requests` library to POST to the apply_setup_ops endpoint. Requires a personal API key with `marketing_analytics:write` scope. The `ops` parameter must be an array of operations returned by `setup_plan`.

```python
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/apply_setup_ops/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ops": "array"
	}
).json()

```

--------------------------------

### Example response for GitHub available installations

Source: https://posthog.com/docs/api/integrations-2

Shows the JSON structure returned by the available_installations endpoint, including installation details and personal GitHub connection status.

```json
{
  "discovery_id": "cdd44607-512c-4795-96df-93dabc33c12d",
  "discovered_at": "2019-08-24T14:15:22Z",
  "personal_github_login": "string",
  "personal_discovery_status": "ok",
  "installations": [
    {
      "installation_id": "string",
      "account_name": "string",
      "account_type": "string",
      "source_team_id": 0,
      "source_team_name": "string"
    }
  ],
  "personal_github_connected": true
}
```
Tokens:
Raw