Vision API Reference

Vision

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

Endpoints

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

← Previous pageNext page →

Create vision scanners affected cohort

Save the users this scanner matched as a static cohort, for surveys, funnels, and retention analysis.

Required API key scopes

replay_scanner:readsession_recording:readcohort:write

Path parameters

id
string

Request parameters

window_days
integer
Default: 30
tag
stringnull
min_score
numbernull
max_score
numbernull

Response

Example request

POST /api/projects/:project_id/vision/scanners/:id/affected_cohort
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/:id/affected_cohort/\
	-d window_days="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision-2_id}/affected_cohort/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"window_days": "integer"
	}
).json()

Example response

Status 201

RESPONSE
{
  "cohort_id": 0,
  "name": "string",
  "users_in_cohort": 0,
  "window_days": 0
}

Create vision scanners bulk observe

Apply this scanner to many sessions on demand. Starts as many as fit under the in-flight caps and monthly credit quota, reporting the rest as skipped rather than failing the batch.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Request parameters

session_ids
array

Response

Example request

POST /api/projects/:project_id/vision/scanners/:id/bulk_observe
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/:id/bulk_observe/\
	-d session_ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision-2_id}/bulk_observe/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"session_ids": "array"
	}
).json()

Example response

Status 202

RESPONSE
{
  "started": 0,
  "results": [
    {
      "session_id": "string",
      "scan_outcome": "started"
    }
  ]
}

Retrieve vision scanners impact

Affected sessions and users for this scanner over the trailing window.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

id
string

Query parameters

max_score
numbernull
min_score
numbernull
tag
stringnull
window_days
integer
Default: 30

Response

Example request

GET /api/projects/:project_id/vision/scanners/:id/impact
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/impact/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision-2_id}/impact/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "affected_sessions": 0,
  "affected_users": 0,
  "sessions_without_user": 0,
  "window_days": 0
}

Create vision scanners observe

Apply this scanner to one specific session, on demand. Returns 202 with the workflow handle.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string

Request parameters

session_id
string

Response

Example request

POST /api/projects/:project_id/vision/scanners/:id/observe
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/:id/observe/\
	-d session_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{vision-2_id}/observe/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"session_id": "string"
	}
).json()

Example response

Status 202

RESPONSE
{
  "workflow_id": "string"
}

List all vision scanners observations

Read-only access to observations produced by a scanner.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

scanner_id
string

Query parameters

date_from
string
date_to
string
labeled
boolean
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"
recording_subject
string
session_id
string
status
string
tags
string
triggered_by
string
verdict
string

Response

Example request

GET /api/projects/:project_id/vision/scanners/:scanner_id/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/scanners/:scanner_id/observations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/observations/".format(
        project_id=project_id,
		scanner_id="<the scanner 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 scanners 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
scanner_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/scanners/:scanner_id/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/scanners/:scanner_id/observations/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/observations/{vision-2_id}/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner 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 scanners 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
scanner_id
string

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/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/scanners/:scanner_id/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/scanners/{scanner_id}/observations/{vision-2_id}/create_task/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner 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 scanners 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
scanner_id
string

Request parameters

is_correct
boolean
feedback
string
Default:

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/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/scanners/:scanner_id/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/scanners/{scanner_id}/observations/{vision-2_id}/label/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"is_correct": "boolean"
	}
).json()

Example response

Status 200

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

Delete vision scanners 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
scanner_id
string

Example request

DELETE /api/projects/:project_id/vision/scanners/:scanner_id/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/scanners/:scanner_id/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/scanners/{scanner_id}/observations/{vision-2_id}/label/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create vision scanners 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
scanner_id
string

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/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/scanners/:scanner_id/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/scanners/{scanner_id}/observations/{vision-2_id}/retry/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "workflow_id": "string"
}

Retrieve vision scanners observations stats

Aggregate counts and per-scanner-type distributions over the filtered observation set. Same filters as the list endpoint apply.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

scanner_id
string

Query parameters

date_from
string
date_to
string
labeled
string
recent_days
integer
recording_subject
string
session_id
string
status
string
tags
string
triggered_by
string
verdict
string

Response

Example request

GET /api/projects/:project_id/vision/scanners/:scanner_id/observations/stats
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/:scanner_id/observations/stats/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/observations/stats/".format(
        project_id=project_id,
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "status_counts": {
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "ineligible": 0,
    "in_flight": 0,
    "success_rate": 0
  },
  "coverage": {
    "recent_sessions": 0,
    "total_sessions": 0,
    "recent_days": 0
  },
  "labels": {
    "up_total": 0,
    "down_total": 0,
    "by_day": [
      {
        "date": "2019-08-24",
        "up": 0,
        "down": 0
      }
    ],
    "by_rating_day": [
      {
        "date": "2019-08-24",
        "up": 0,
        "down": 0
      }
    ],
    "version_markers": [
      {
        "date": "2019-08-24",
        "version": 0,
        "prompt": "string",
        "scanner_config": null,
        "up": 0,
        "down": 0,
        "total": 0
      }
    ]
  },
  "available_tags": [
    "string"
  ],
  "monitor": {
    "yes_total": 0,
    "no_total": 0,
    "inconclusive_total": 0
  },
  "classifier": {
    "fixed_ranked": [
      {
        "tag": "string",
        "count": 0
      }
    ],
    "freeform_ranked": [
      {
        "tag": "string",
        "count": 0
      }
    ],
    "total_with_tags": 0
  },
  "scorer": {
    "summary": {
      "min": 0.1,
      "p25": 0.1,
      "median": 0.1,
      "mean": 0.1,
      "p75": 0.1,
      "max": 0.1,
      "count": 0
    },
    "histogram": {
      "labels": [
        "string"
      ],
      "counts": [
        0
      ]
    }
  }
}

List all vision scanners prompt suggestions

AI prompt-rewrite suggestions for a scanner, generated from the team's thumbs up/down ratings.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

scanner_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions
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/:scanner_id/prompt_suggestions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/".format(
        project_id=project_id,
		scanner_id="<the scanner 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": "pending",
      "suggested_prompt": "string",
      "base_prompt": "string",
      "base_config": null,
      "suggested_config": null,
      "changes": null,
      "rationale": "string",
      "based_on_up": 0,
      "based_on_down": 0,
      "scanner_version": 0,
      "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"
      },
      "applied_at": "2019-08-24T14:15:22Z",
      "applied_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"
      },
      "evaluation": {
        "status": "string",
        "started_at": "2019-08-24T14:15:22Z",
        "finished_at": "2019-08-24T14:15:22Z",
        "total": 0,
        "labels_fingerprint": "string",
        "results": [
          {
            "session_id": "string",
            "observation_id": "string",
            "rated_correct": true,
            "before": "string",
            "after": "string",
            "outcome": "string",
            "error": "string"
          }
        ],
        "summary": {
          "kept": 0,
          "regressed": 0,
          "fixed": 0,
          "still_wrong": 0,
          "errors": 0
        }
      }
    }
  ]
}

Create vision scanners prompt suggestions apply

Apply this suggestion: write a config to the scanner (the prompt plus any type-specific config such as classifier tags or the monitor allow_inconclusive flag), bumping the scanner version, and mark the suggestion applied. Pass config to apply an edited subset of the recommendation; omit it to apply the full suggested config. Only the current pending suggestion can be applied. Requires session recording edit access.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string
scanner_id
string

Request parameters

config

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions/:id/apply
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/:scanner_id/prompt_suggestions/:id/apply/\
	-d config=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/{vision-2_id}/apply/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "base_config": null,
  "suggested_config": null,
  "changes": null,
  "rationale": "string",
  "based_on_up": 0,
  "based_on_down": 0,
  "scanner_version": 0,
  "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"
  },
  "applied_at": "2019-08-24T14:15:22Z",
  "applied_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"
  },
  "evaluation": {
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "labels_fingerprint": "string",
    "results": [
      {
        "session_id": "string",
        "observation_id": "string",
        "rated_correct": true,
        "before": "string",
        "after": "string",
        "outcome": "string",
        "error": "string"
      }
    ],
    "summary": {
      "kept": 0,
      "regressed": 0,
      "fixed": 0,
      "still_wrong": 0,
      "errors": 0
    }
  }
}

Create vision scanners prompt suggestions dismiss

Dismiss this suggestion without applying it. Only the current pending suggestion can be dismissed. Requires editor access to the scanner.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string
scanner_id
string

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions/:id/dismiss
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/:scanner_id/prompt_suggestions/:id/dismiss/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/{vision-2_id}/dismiss/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "base_config": null,
  "suggested_config": null,
  "changes": null,
  "rationale": "string",
  "based_on_up": 0,
  "based_on_down": 0,
  "scanner_version": 0,
  "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"
  },
  "applied_at": "2019-08-24T14:15:22Z",
  "applied_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"
  },
  "evaluation": {
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "labels_fingerprint": "string",
    "results": [
      {
        "session_id": "string",
        "observation_id": "string",
        "rated_correct": true,
        "before": "string",
        "after": "string",
        "outcome": "string",
        "error": "string"
      }
    ],
    "summary": {
      "kept": 0,
      "regressed": 0,
      "fixed": 0,
      "still_wrong": 0,
      "errors": 0
    }
  }
}

Create vision scanners prompt suggestions evaluate

Test this suggestion before applying it: re-run the scanner with the suggested prompt against already-rated sessions in the background and compare each fresh output with the stored one. Results land on the suggestion's evaluation field. Poll current while status is running. session_limit controls how many rated sessions are re-run (thumbs-down prioritized, up to evaluation_session_cap). Each successful re-run charges credits like a normal observation of the same model. The request is refused with 402 when the planned credits exceed what is left of the monthly limit. Monitor and classifier scanners get a kept/fixed/regressed classification, while scorer and summarizer scanners show the raw before and after output. Requires session recording edit access.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

id
string
scanner_id
string

Request parameters

session_limit
integer
Default: 10
config

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions/:id/evaluate
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/:scanner_id/prompt_suggestions/:id/evaluate/\
	-d session_limit="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/{vision-2_id}/evaluate/".format(
        project_id=project_id,
		vision-2_id="<the vision-2 id>",
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"session_limit": "integer"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "base_config": null,
  "suggested_config": null,
  "changes": null,
  "rationale": "string",
  "based_on_up": 0,
  "based_on_down": 0,
  "scanner_version": 0,
  "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"
  },
  "applied_at": "2019-08-24T14:15:22Z",
  "applied_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"
  },
  "evaluation": {
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "labels_fingerprint": "string",
    "results": [
      {
        "session_id": "string",
        "observation_id": "string",
        "rated_correct": true,
        "before": "string",
        "after": "string",
        "outcome": "string",
        "error": "string"
      }
    ],
    "summary": {
      "kept": 0,
      "regressed": 0,
      "fixed": 0,
      "still_wrong": 0,
      "errors": 0
    }
  }
}

Retrieve vision scanners prompt suggestions current

The scanner's newest prompt suggestion plus whether it is stale (the ratings changed since it was generated) and how many rated observations are available.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

scanner_id
string

Response

Example request

GET /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions/current
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/:scanner_id/prompt_suggestions/current/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/current/".format(
        project_id=project_id,
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "suggestion": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "suggested_prompt": "string",
    "base_prompt": "string",
    "base_config": null,
    "suggested_config": null,
    "changes": null,
    "rationale": "string",
    "based_on_up": 0,
    "based_on_down": 0,
    "scanner_version": 0,
    "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"
    },
    "applied_at": "2019-08-24T14:15:22Z",
    "applied_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"
    },
    "evaluation": {
      "status": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "finished_at": "2019-08-24T14:15:22Z",
      "total": 0,
      "labels_fingerprint": "string",
      "results": [
        {
          "session_id": "string",
          "observation_id": "string",
          "rated_correct": true,
          "before": "string",
          "after": "string",
          "outcome": "string",
          "error": "string"
        }
      ],
      "summary": {
        "kept": 0,
        "regressed": 0,
        "fixed": 0,
        "still_wrong": 0,
        "errors": 0
      }
    }
  },
  "stale": true,
  "rated_count": 0,
  "evaluation_session_cap": 0
}

Create vision scanners prompt suggestions generate

Generate a fresh prompt suggestion from the team's current ratings. The previous pending suggestion becomes history (superseded). Requires at least one rated observation and editor access to the scanner.

Required API key scopes

replay_scanner:writesession_recording:read

Path parameters

scanner_id
string

Response

Example request

POST /api/projects/:project_id/vision/scanners/:scanner_id/prompt_suggestions/generate
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/:scanner_id/prompt_suggestions/generate/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/{scanner_id}/prompt_suggestions/generate/".format(
        project_id=project_id,
		scanner_id="<the scanner id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "base_config": null,
  "suggested_config": null,
  "changes": null,
  "rationale": "string",
  "based_on_up": 0,
  "based_on_down": 0,
  "scanner_version": 0,
  "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"
  },
  "applied_at": "2019-08-24T14:15:22Z",
  "applied_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"
  },
  "evaluation": {
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "finished_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "labels_fingerprint": "string",
    "results": [
      {
        "session_id": "string",
        "observation_id": "string",
        "rated_correct": true,
        "before": "string",
        "after": "string",
        "outcome": "string",
        "error": "string"
      }
    ],
    "summary": {
      "kept": 0,
      "regressed": 0,
      "fixed": 0,
      "still_wrong": 0,
      "errors": 0
    }
  }
}

Retrieve vision scanners creators

Distinct creators across the team's scanners — feeds the Created by filter dropdown.

Required API key scopes

replay_scanner:read

Response

Example request

GET /api/projects/:project_id/vision/scanners/creators
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/creators/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/creators/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "creators": [
    {
      "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"
    }
  ]
}

Create vision scanners estimate

Estimate the observation volume a proposed scanner would generate, for the pre-save cost preview.

Required API key scopes

replay_scanner:readsession_recording:read

Request parameters

query
sampling_rate
number
Default: 1
sampling_mode
Default: comprehensive
scanner_id
stringnull
model
Default: gemini-3-flash-preview

Response

Example request

POST /api/projects/:project_id/vision/scanners/estimate
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/estimate/\
	-d query=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/estimate/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "matched_sessions_in_window": 0,
  "window_days": 0,
  "estimated_observations_per_month": 0,
  "credits_per_observation": 0,
  "estimated_credits_per_month": 0,
  "other_enabled_scanners_monthly_credits": 0,
  "sampling_rate": 0.1
}

Retrieve vision scanners stats

Team-wide scanner counts — independent of list filters, so the overview stays stable.

Required API key scopes

replay_scanner:read

Response

Example request

GET /api/projects/:project_id/vision/scanners/stats
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/stats/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/vision/scanners/stats/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "total": 0,
  "enabled": 0,
  "by_type": {
    "monitor": {
      "enabled": 0,
      "total": 0
    },
    "classifier": {
      "enabled": 0,
      "total": 0
    },
    "scorer": {
      "enabled": 0,
      "total": 0
    },
    "summarizer": {
      "enabled": 0,
      "total": 0
    }
  }
}

← Previous pageNext page →