Vision API Reference

Vision

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`POST`
`GET`
`GET`
`GET`
`GET`
`POST`
`POST`
`DELETE`
`POST`
`GET`
`GET`
`POST`
`GET`
`PATCH`
`DELETE`

List all vision actions

CRUD for Replay Vision actions — scheduled "and then…" automations over a scanner's observations.

Required API key scopes

vision_action:read

Query parameters

limit
integer
offset
integer
scanner
string

Response

Example request

GET /api/projects/:project_id/vision/actions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "scanner": "13126d94-3004-4e8d-9b94-45be2ca907ee",
      "enabled": true,
      "is_scanner_digest": true,
      "trigger_type": "schedule",
      "mode": "group_summary",
      "trigger_config": {
        "rrule": "string",
        "timezone": "UTC"
      },
      "selection": {
        "scanner_ids": [
          "string"
        ],
        "verdict": [
          "yes"
        ],
        "tags": [
          "string"
        ],
        "min_score": 0.1,
        "max_score": 0.1
      },
      "synthesis_config": {
        "prompt_guide": "string"
      },
      "alert_config": {
        "frequency": "on_breach",
        "metric": "count",
        "threshold": 0.1,
        "direction": "above",
        "window_days": 1
      },
      "delivery_config": [
        {
          "type": "slack",
          "integration_id": 0,
          "channel": "string"
        }
      ],
      "next_run_at": "2019-08-24T14:15:22Z",
      "last_run_at": "2019-08-24T14:15:22Z",
      "hog_flow_id": "07371c7a-9bb6-4ac0-aeea-5616bed86938",
      "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"
      },
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create vision actions

CRUD for Replay Vision actions — scheduled "and then…" automations over a scanner's observations.

Required API key scopes

vision_action:writesession_recording:read

Request parameters

name
string
scanner
string
enabled
boolean
is_scanner_digest
boolean
trigger_type
mode
trigger_config
selection
synthesis_config
alert_config
delivery_config
array

Response

Example request

POST /api/projects/:project_id/vision/actions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/\
	-d name="string",\
	-d scanner="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string",
		"scanner": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "scanner": "13126d94-3004-4e8d-9b94-45be2ca907ee",
  "enabled": true,
  "is_scanner_digest": true,
  "trigger_type": "schedule",
  "mode": "group_summary",
  "trigger_config": {
    "rrule": "string",
    "timezone": "UTC"
  },
  "selection": {
    "scanner_ids": [
      "string"
    ],
    "verdict": [
      "yes"
    ],
    "tags": [
      "string"
    ],
    "min_score": 0.1,
    "max_score": 0.1
  },
  "synthesis_config": {
    "prompt_guide": "string"
  },
  "alert_config": {
    "frequency": "on_breach",
    "metric": "count",
    "threshold": 0.1,
    "direction": "above",
    "window_days": 1
  },
  "delivery_config": [
    {
      "type": "slack",
      "integration_id": 0,
      "channel": "string"
    }
  ],
  "next_run_at": "2019-08-24T14:15:22Z",
  "last_run_at": "2019-08-24T14:15:22Z",
  "hog_flow_id": "07371c7a-9bb6-4ac0-aeea-5616bed86938",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve vision actions

CRUD for Replay Vision actions — scheduled "and then…" automations over a scanner's observations.

Required API key scopes

vision_action:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/vision/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "scanner": "13126d94-3004-4e8d-9b94-45be2ca907ee",
  "enabled": true,
  "is_scanner_digest": true,
  "trigger_type": "schedule",
  "mode": "group_summary",
  "trigger_config": {
    "rrule": "string",
    "timezone": "UTC"
  },
  "selection": {
    "scanner_ids": [
      "string"
    ],
    "verdict": [
      "yes"
    ],
    "tags": [
      "string"
    ],
    "min_score": 0.1,
    "max_score": 0.1
  },
  "synthesis_config": {
    "prompt_guide": "string"
  },
  "alert_config": {
    "frequency": "on_breach",
    "metric": "count",
    "threshold": 0.1,
    "direction": "above",
    "window_days": 1
  },
  "delivery_config": [
    {
      "type": "slack",
      "integration_id": 0,
      "channel": "string"
    }
  ],
  "next_run_at": "2019-08-24T14:15:22Z",
  "last_run_at": "2019-08-24T14:15:22Z",
  "hog_flow_id": "07371c7a-9bb6-4ac0-aeea-5616bed86938",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Update vision actions

CRUD for Replay Vision actions — scheduled "and then…" automations over a scanner's observations.

Required API key scopes

vision_action:writesession_recording:read

Path parameters

id
string

Request parameters

name
string
scanner
string
enabled
boolean
is_scanner_digest
boolean
trigger_type
mode
trigger_config
selection
synthesis_config
alert_config
delivery_config
array

Response

Example request

PATCH /api/projects/:project_id/vision/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "scanner": "13126d94-3004-4e8d-9b94-45be2ca907ee",
  "enabled": true,
  "is_scanner_digest": true,
  "trigger_type": "schedule",
  "mode": "group_summary",
  "trigger_config": {
    "rrule": "string",
    "timezone": "UTC"
  },
  "selection": {
    "scanner_ids": [
      "string"
    ],
    "verdict": [
      "yes"
    ],
    "tags": [
      "string"
    ],
    "min_score": 0.1,
    "max_score": 0.1
  },
  "synthesis_config": {
    "prompt_guide": "string"
  },
  "alert_config": {
    "frequency": "on_breach",
    "metric": "count",
    "threshold": 0.1,
    "direction": "above",
    "window_days": 1
  },
  "delivery_config": [
    {
      "type": "slack",
      "integration_id": 0,
      "channel": "string"
    }
  ],
  "next_run_at": "2019-08-24T14:15:22Z",
  "last_run_at": "2019-08-24T14:15:22Z",
  "hog_flow_id": "07371c7a-9bb6-4ac0-aeea-5616bed86938",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z"
}

Delete vision actions

CRUD for Replay Vision actions — scheduled "and then…" automations over a scanner's observations.

Required API key scopes

vision_action:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/vision/actions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create vision actions run

Run this summary now, without waiting for its schedule — synthesizes a group summary over the observations since the last summary (or the last 24h). The recurring schedule is untouched: the engine advances next_run_at only at scheduled claim time, never in the run itself.

Required API key scopes

vision_action:writesession_recording:read

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/vision/actions/:id/run
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:id/run/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_id}/run/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "workflow_id": "string",
  "already_running": true
}

List all vision actions runs

Read-only run history for a single vision action (nested under /vision/actions/{action_id}/runs/).

Required API key scopes

vision_action:readsession_recording:read

Path parameters

vision_action_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/vision/actions/:vision_action_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:vision_action_id/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_action_id}/runs/".format(
        project_id=project_id,
		vision_action_id="<the vision action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "running",
      "scheduled_at": "2019-08-24T14:15:22Z",
      "observation_count": 0,
      "error_reason": "string",
      "is_recovery": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve vision actions runs

Read-only run history for a single vision action (nested under /vision/actions/{action_id}/runs/).

Required API key scopes

vision_action:readsession_recording:read

Path parameters

id
string
vision_action_id
string

Response

Example request

GET /api/projects/:project_id/vision/actions/:vision_action_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/actions/:vision_action_id/runs/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/actions/{vision_action_id}/runs/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>",
		vision_action_id="<the vision action id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "running",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "observation_count": 0,
  "error_reason": "string",
  "is_recovery": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "synthesized_markdown": "string",
  "observations": [
    {
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "session_id": "string",
      "recording_subject_email": "string",
      "title": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

List all vision observations

Read-only access to a session's observations across every scanner the caller can read, for the replay-page dock.

Required API key scopes

replay_scanner:readsession_recording:read

Query parameters

limit
integer
offset
integer
order_by
string
One of: "-completed_at""-created_at""-label""-recording_subject_email""-result_confidence""-result_score""-result_verdict""-scanner_version""-started_at""-status""completed_at""created_at""label""recording_subject_email""result_confidence""result_score""result_verdict""scanner_version""started_at""status"
session_id
string

Response

Example request

GET /api/projects/:project_id/vision/observations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "scanner_id": "43593f58-da3f-45f0-a7bf-8763ef29bdf1",
      "session_id": "string",
      "status": "pending",
      "error_reason": "string",
      "workflow_id": "string",
      "scanner_snapshot": {
        "name": "string",
        "scanner_type": "monitor",
        "scanner_version": 0,
        "model": "string",
        "provider": "string",
        "emits_signals": true,
        "scanner_config": null
      },
      "scanner_result": {
        "model_output": null,
        "signals_count": 0
      },
      "triggered_by": "schedule",
      "triggered_by_user": {
        "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"
      },
      "distinct_id": "string",
      "recording_subject_email": "string",
      "previous_observation_id": "bdc4be48-ad44-4150-aaf7-80ca533d4bac",
      "next_observation_id": "67a517e1-9b1d-4c86-8d8e-6ec9b5738f26",
      "label": {
        "is_correct": true,
        "feedback": ""
      },
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve vision observations

Retrieve one observation. Any list filters passed along (status, tags, order_by, …) scope the previous_observation_id/next_observation_id navigation to the matching, identically-ordered set — so prev/next from a filtered table stays within that filtered list.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

id
string

Query parameters

date_from
string
date_to
string
labeled
string
order_by
string
One of: "-completed_at""-created_at""-label""-recording_subject_email""-result_confidence""-result_score""-result_verdict""-scanner_version""-started_at""-status""completed_at""created_at""label""recording_subject_email""result_confidence""result_score""result_verdict""scanner_version""started_at""status"
recording_subject
string
session_id
string
status
string
tags
string
triggered_by
string
verdict
string

Response

Example request

GET /api/projects/:project_id/vision/observations/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "scanner_id": "43593f58-da3f-45f0-a7bf-8763ef29bdf1",
  "session_id": "string",
  "status": "pending",
  "error_reason": "string",
  "workflow_id": "string",
  "scanner_snapshot": {
    "name": "string",
    "scanner_type": "monitor",
    "scanner_version": 0,
    "model": "string",
    "provider": "string",
    "emits_signals": true,
    "scanner_config": null
  },
  "scanner_result": {
    "model_output": null,
    "signals_count": 0
  },
  "triggered_by": "schedule",
  "triggered_by_user": {
    "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"
  },
  "distinct_id": "string",
  "recording_subject_email": "string",
  "previous_observation_id": "bdc4be48-ad44-4150-aaf7-80ca533d4bac",
  "next_observation_id": "67a517e1-9b1d-4c86-8d8e-6ec9b5738f26",
  "label": {
    "is_correct": true,
    "feedback": ""
  },
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Create vision observations create task

Create a PostHog Task from this observation's finding so it can be triaged and fixed. Title and description are derived from the scanner and its result. Record-only: this does not start the coding agent. Idempotent per observation: once a task exists, repeat calls return its id with a 200 instead of creating a duplicate.

Required API key scopes

replay_scanner:writesession_recording:readtask:write

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/vision/observations/:id/create_task
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/:id/create_task/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/{vision_id}/create_task/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

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

Status 201

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

Create vision observations label

Set or update the observation's shared label: whether the scanner scored the session correctly, plus optional feedback on what it got wrong. One label per observation, shared across the team; these labels feed prompt improvement. Requires editor access to the scanner.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Request parameters

is_correct
boolean
feedback
string
Default:

Response

Example request

POST /api/projects/:project_id/vision/observations/:id/label
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/:id/label/\
	-d is_correct="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/{vision_id}/label/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"is_correct": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "is_correct": true,
  "feedback": ""
}

Delete vision observations label

Remove the observation's shared label. Requires editor access to the scanner.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/vision/observations/:id/label
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/:id/label/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/{vision_id}/label/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create vision observations retry

Delete a failed observation and re-run its scanner on the same recording. Returns 202 with the workflow handle.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/vision/observations/:id/retry
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/observations/:id/retry/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/observations/{vision_id}/retry/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "workflow_id": "string"
}

Retrieve environment vision quota

Required API key scopes

replay_scanner:read

Response

Example request

GET /api/projects/:project_id/vision/quota
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/quota/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/quota/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "credit_limit": 0,
  "credits_used": 0,
  "remaining": 0,
  "exhausted": true,
  "period_start": "2019-08-24T14:15:22Z",
  "period_end": "2019-08-24T14:15:22Z",
  "projected_monthly_credits": 0
}

List all vision scanners

CRUD for Replay Vision scanners.

Required API key scopes

replay_scanner:read

Query parameters

created_by
string
emits_signals
boolean
enabled
string
limit
integer
offset
integer
order_by
string
One of: "-created_at""-created_by""-credits_this_month""-enabled""-name""-sampling_rate""-scanner_type""-updated_at""created_at""created_by""credits_this_month""enabled""name""sampling_rate""scanner_type""updated_at"
scanner_type
string
search
string

Response

Example request

GET /api/projects/:project_id/vision/scanners
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/scanners/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "scanner_type": "monitor",
      "scanner_config": null,
      "query": null,
      "sampling_rate": 1,
      "sampling_mode": "focused",
      "provider": "google",
      "model": "gemini-3.5-flash-lite",
      "enabled": true,
      "emits_signals": true,
      "scanner_version": 0,
      "estimated_monthly_observations": 0,
      "credits_per_observation": 0,
      "estimated_monthly_credits": 0,
      "credits_this_month": 0,
      "last_swept_at": "2019-08-24T14:15:22Z",
      "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"
      },
      "updated_at": "2019-08-24T14:15:22Z",
      "feedback_themes": {
        "themes": [
          {
            "theme": "string",
            "count": 0,
            "examples": [
              "string"
            ],
            "sessions": [
              {
                "observation_id": "string",
                "session_id": "string"
              }
            ]
          }
        ],
        "feedback_count": 0,
        "generated_at": "2019-08-24T14:15:22Z"
      },
      "user_access_level": "string"
    }
  ]
}

Create vision scanners

CRUD for Replay Vision scanners.

Required API key scopes

replay_scanner:writesession_recording:read

Request parameters

name
string
description
string
scanner_type
scanner_config
query
sampling_rate
number
sampling_mode
provider
model
enabled
boolean
emits_signals
boolean

Response

Example request

POST /api/projects/:project_id/vision/scanners
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/scanners/\
	-d name="string",\
	-d scanner_type=undefined,\
	-d scanner_config=undefined,\
	-d model=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "scanner_type": "monitor",
  "scanner_config": null,
  "query": null,
  "sampling_rate": 1,
  "sampling_mode": "focused",
  "provider": "google",
  "model": "gemini-3.5-flash-lite",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 0,
  "credits_this_month": 0,
  "last_swept_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "feedback_themes": {
    "themes": [
      {
        "theme": "string",
        "count": 0,
        "examples": [
          "string"
        ],
        "sessions": [
          {
            "observation_id": "string",
            "session_id": "string"
          }
        ]
      }
    ],
    "feedback_count": 0,
    "generated_at": "2019-08-24T14:15:22Z"
  },
  "user_access_level": "string"
}

Retrieve vision scanners

CRUD for Replay Vision scanners.

Required API key scopes

replay_scanner:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/vision/scanners/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/scanners/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "scanner_type": "monitor",
  "scanner_config": null,
  "query": null,
  "sampling_rate": 1,
  "sampling_mode": "focused",
  "provider": "google",
  "model": "gemini-3.5-flash-lite",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 0,
  "credits_this_month": 0,
  "last_swept_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "feedback_themes": {
    "themes": [
      {
        "theme": "string",
        "count": 0,
        "examples": [
          "string"
        ],
        "sessions": [
          {
            "observation_id": "string",
            "session_id": "string"
          }
        ]
      }
    ],
    "feedback_count": 0,
    "generated_at": "2019-08-24T14:15:22Z"
  },
  "user_access_level": "string"
}

Update vision scanners

CRUD for Replay Vision scanners.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Request parameters

name
string
description
string
scanner_type
scanner_config
query
sampling_rate
number
sampling_mode
provider
model
enabled
boolean
emits_signals
boolean

Response

Example request

PATCH /api/projects/:project_id/vision/scanners/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/scanners/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "scanner_type": "monitor",
  "scanner_config": null,
  "query": null,
  "sampling_rate": 1,
  "sampling_mode": "focused",
  "provider": "google",
  "model": "gemini-3.5-flash-lite",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 0,
  "credits_this_month": 0,
  "last_swept_at": "2019-08-24T14:15:22Z",
  "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"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "feedback_themes": {
    "themes": [
      {
        "theme": "string",
        "count": 0,
        "examples": [
          "string"
        ],
        "sessions": [
          {
            "observation_id": "string",
            "session_id": "string"
          }
        ]
      }
    ],
    "feedback_count": 0,
    "generated_at": "2019-08-24T14:15:22Z"
  },
  "user_access_level": "string"
}

Delete vision scanners

CRUD for Replay Vision scanners.

Required API key scopes

replay_scanner:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/vision/scanners/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/vision/scanners/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision_id}/".format(
        project_id=project_id,
		vision_id="<the vision id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)