PostHog sessions

Import real-user PostHog session replays as user-session runs: the session is fetched, converted into a trace, and reviewed by the same auditor that reviews agent runs. Findings produced this way carry origin=user_session. A per-project PostHog connection (host, project, personal API key with the session_recording:read and query:read scopes) must be configured first, including an explicit acknowledgement that importing real end-user behavioral data is authorized. Reading imported sessions back: each import is a recording (GET /api/v1/recordings?source_type=posthog; external_ref holds the PostHog session id) linked to an anchor run (GET /api/v1/agents?source=posthog_session) whose summary holds the audit verdict; POST /api/v1/recordings/{id}/reproduce turns a session into a runnable test. See rfc/20260805_user_sessions_as_agent_runs.md.

POST /api/v1/posthog/sessions

Import a PostHog session replay

Queues the import of one PostHog session replay into the audit trail. The session is fetched, scrubbed, stored as a recording, and audited asynchronously; the response carries only acceptance. Pass report_text when a user report triggered the import — the auditor uses it as the goal of a targeted review.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	body	Yes	Project to import the session into
`session_id`	string	body	Yes	PostHog session (replay) id — the path segment after /replay/ in a replay URL
`report_text`	string	body	No	Optional user report or complaint text; becomes the goal of the audit

Status Codes

Code	Description
`202`	Import queued (duplicate=true when the same session is already queued)
`400`	project_id and session_id are required
`401`	Unauthorized
`503`	PostHog ingest is not configured on this deployment

Response Body

{
  "queued": true,
  "duplicate": false,
  "session_id": "019fb29a-dd2c-7ae6-a281-5d65f05109f5"
}

API Key

project_id *

session_id *

report_text

cURL

Response

PUT /api/v1/posthog/connections

Create or update a project's PostHog connection

Stores the PostHog connection session imports read from and verifies the key's scopes up front, so a missing scope fails here rather than inside a queued import. The key must be a personal API key carrying the session_recording:read and query:read scopes. real_user_data_ack records the customer's explicit authorization to import real end-user session data.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	body	Yes	Project the connection belongs to
`host`	string	body	Yes	PostHog instance base URL
`posthog_project_id`	string	body	Yes	PostHog project id sessions are read from
`api_key`	string	body	Yes	PostHog personal API key with the session_recording:read and query:read scopes
`capture_token`	string	body	No	Optional: the PostHog project's 'Project API key' (phc_..., found under Settings → Project — the same token web snippets use, distinct from the personal API key). When set, completed agent runs are exported into this PostHog project as aiqa_agent_run events
`real_user_data_ack`	boolean	body	Yes	Explicit acknowledgement that importing real end-user session data is authorized

Status Codes

Code	Description
`200`	Connection stored and verified
`400`	Validation error
`401`	Unauthorized
`422`	API key is missing a required scope

Response Body

{
  "connected": true,
  "host": "https://eu.posthog.com",
  "posthog_project_id": "198840",
  "real_user_data_ack": true,
  "last_verified_at": "2026-08-05T09:30:00Z"
}

API Key

project_id *

host *

posthog_project_id *

api_key *

capture_token

real_user_data_ack *

cURL

Response

PATCH /api/v1/posthog/connections

Update a connection's auto-ingest settings

Changes the signal-driven auto-ingest settings without resubmitting credentials: when enabled, sessions with friction signals (rage clicks, exceptions) are imported and audited automatically, bounded by the daily cap.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	body	Yes	Project whose connection to update
`auto_ingest_enabled`	boolean	body	Yes	Turn the friction-signal session poller on or off
`auto_ingest_daily_cap`	int	body	No	Maximum sessions auto-imported per UTC day (1-100) (default: 10)

Status Codes

Code	Description
`200`	Settings updated
`400`	Validation error
`401`	Unauthorized
`404`	No connection for this project

Response Body

{
  "connected": true,
  "host": "https://eu.posthog.com",
  "posthog_project_id": "198840",
  "real_user_data_ack": true,
  "last_verified_at": "2026-08-05T09:30:00Z"
}

API Key

project_id *

auto_ingest_enabled *

auto_ingest_daily_cap

cURL

Response

GET /api/v1/posthog/connections

Get a project's PostHog connection

Returns the project's PostHog connection status. The API key itself is never returned.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	Yes	Project to look up

Status Codes

Code	Description
`200`	OK
`400`	Missing or invalid project_id
`401`	Unauthorized
`404`	No connection configured for this project

Response Body

{
  "connected": true,
  "host": "https://eu.posthog.com",
  "posthog_project_id": "198840",
  "real_user_data_ack": true,
  "last_verified_at": "2026-08-05T09:30:00Z"
}

API Key

project_id *

cURL

Response

DELETE /api/v1/posthog/connections

Remove a project's PostHog connection

Deletes the project's PostHog connection. Sessions already imported are unaffected; new imports fail until a connection is configured again.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	Yes	Project whose connection to remove

Status Codes

Code	Description
`204`	Connection removed
`400`	Missing or invalid project_id
`401`	Unauthorized

API Key

project_id *

cURL

Response