Vision-2

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

Endpoints

GET
PATCH
DELETE
POST
GET
GET
GET
GET
POST
GET
← Previous page

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/

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,
  "provider": "google",
  "model": "gemini-3-flash-preview",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 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"
}

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
  • 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"

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,
  "provider": "google",
  "model": "gemini-3-flash-preview",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 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"
}

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/

Example response

Status 204 No response body

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"

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

  • limit
    integer
  • offset
    integer
  • order_by
    string
    One of: "-completed_at""-created_at""-result_score""-result_verdict""-scanner_version""-started_at""-status""completed_at""created_at""result_score""result_verdict""scanner_version""started_at""status"
  • 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/

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": "gemini-3-flash-preview",
        "provider": "google",
        "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"
      },
      "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

Read-only access to observations produced by a scanner.

Required API key scopes

replay_scanner:readsession_recording:read

Path parameters

  • id
    string
  • scanner_id
    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/

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": "gemini-3-flash-preview",
    "provider": "google",
    "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"
  },
  "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 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

  • recent_days
    integer
  • 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/

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
  },
  "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
      ]
    }
  }
}

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/

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

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

Example response

Status 200
RESPONSE
{
  "matched_sessions_in_window": 0,
  "window_days": 0,
  "estimated_observations_per_month": 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/

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 page

Community questions

Questions about this page? or post a community question.