Vision

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

Endpoints

GET
GET
POST
GET
PATCH
DELETE
POST
GET
GET
POST
DELETE
POST
GET
GET
POST
POST
POST
GET
POST
GET
← Previous pageNext page →

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/

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""-enabled""-name""-sampling_rate""-scanner_type""-updated_at""created_at""created_by""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/

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-2.5-flash",
      "enabled": true,
      "emits_signals": true,
      "scanner_version": 0,
      "estimated_monthly_observations": 0,
      "credits_per_observation": 0,
      "estimated_monthly_credits": 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"
    }
  ]
}

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

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-2.5-flash",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 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"
}

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,
  "sampling_mode": "focused",
  "provider": "google",
  "model": "gemini-2.5-flash",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 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
  • 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"

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-2.5-flash",
  "enabled": true,
  "emits_signals": true,
  "scanner_version": 0,
  "estimated_monthly_observations": 0,
  "credits_per_observation": 0,
  "estimated_monthly_credits": 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

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

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

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

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 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 session recording edit access.

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"

Example response

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

Delete vision scanners observations label

Remove the observation's shared label. Requires session recording edit access.

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/

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/

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

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

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",
        "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/

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",
      "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 its prompt to the scanner (bumping the scanner version) and mark the suggestion applied. 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

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/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "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 session recording edit access.

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/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "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. Only monitor and classifier scanners are supported. 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

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"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "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/

Example response

Status 200
RESPONSE
{
  "suggestion": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "suggested_prompt": "string",
    "base_prompt": "string",
    "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 session recording edit access.

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/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "pending",
  "suggested_prompt": "string",
  "base_prompt": "string",
  "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/

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"
    }
  ]
}
← Previous pageNext page →

Community questions

Questions about this page? or post a community question.