Signals

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

Endpoints

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

Create signals scout chat tasks

Create and run a cloud task for one of the fixed scout chat templates (suggest a scout, fleet overview, recent signals). The prompt is server-owned; an author_scout chat can carry the user's request, which the server fences inside that prompt. The response carries the task id to navigate to.

Required API key scopes

task:write

Request parameters

  • chat_type
  • suggestion_id
    string
  • user_prompt
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/chat_tasks
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/signals/scout/chat_tasks/\
-d chat_type=undefined

Example response

Status 201 Chat task created and run started
RESPONSE
{
"task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}
Status 403 Organization has not approved AI data processing
Status 429 Team is over its posthog_code usage limit

List all signals scout config

List the per-(team, skill) scout configs for this project. Each row includes its display_name (the label people read), its skill_name (the permanent identifier), its schedule (rolling run_interval_minutes, or a project-local run_cron_schedule when set), enabled, emit posture, and tags. A freshly authored scout skill appears here once its config is registered, either explicitly via create or by the coordinator's next tick. Pass tags to narrow the fleet to the scouts carrying at least one of the given labels, and search to narrow it to the scouts matching a substring of either name.

Required API key scopes

signal_scout:read

Query parameters

  • search
    string
  • tags
    string

Example request

GET /api/projects/:project_id/signals/scout/configs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/

Example response

Status 200 Per-scout configs for this project, ordered by the name each scout displays under.
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"skill_name": "string",
"description": "string",
"display_name": "string",
"scout_origin": "canonical",
"scout_role": "specialist",
"deprecation": {
"phase": "announced",
"reason": "string",
"superseded_by": "string",
"sunset_at": "2019-08-24T14:15:22Z"
},
"owners": [
{
"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"
}
],
"enabled": true,
"status": "active",
"pause_reason": "no_output",
"managed_by": "team",
"emit": true,
"run_interval_minutes": 30,
"run_cron_schedule": "string",
"output_destinations": {
"slack": {
"integration_id": 1,
"channel": "string",
"users": [
"string"
],
"thread_reports": true
},
"webhook": {
"hog_function_id": "string"
},
"inbox": true
},
"structured_output_schema": {},
"network_access": "trusted",
"model": "string",
"custom_image_id": "871a86c2-b20e-4ced-8336-55149e45aaf7",
"mcp_gateway_server_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"repositories": [
"string"
],
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"max_report_actions_per_day": 20,
"lifecycle_locked": true,
"allowed_mcp_tools": [
"string"
],
"tool_preset": "string",
"precheck_query": "string",
"precheck_disabled": true,
"effective_precheck_query": "string",
"precheck_query_source": "config",
"last_precheck_at": "2019-08-24T14:15:22Z",
"last_precheck_outcome": "run",
"last_precheck_row_count": 0,
"last_run_at": "2019-08-24T14:15:22Z",
"consecutive_failure_count": 0,
"status_changed_at": "2019-08-24T14:15:22Z",
"status_changed_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"
},
"auto_pause_exempt": true,
"tags": [
"string"
],
"source_product": "string",
"source_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Create signals scout config

Register the config for a skill immediately, without waiting for the coordinator to auto-register it — and the way to make a skill without the signals-scout- prefix a scout at all. The same call can optionally set run_interval_minutes, a cron run_cron_schedule, enabled, emit, network_access, and output destinations. The skill must already exist on this project. Upsert: if a config already exists for the skill, the provided fields are applied to it. Registering puts the skill's body on the schedule as the scout's prompt, so this call needs llm_skill:write and editor access to skills on top of signal_scout:write, like creating a scout.

Required API key scopes

signal_scout:writellm_skill:write

Request parameters

  • model
    string | null
  • custom_image_id
    string | null
  • tags
    array
  • structured_output_schema
    object | null
  • mcp_gateway_server_ids
    array
  • repositories
    array
  • write_scopes
    array
  • report_actions
    array
  • max_report_actions_per_day
    integer
  • lifecycle_locked
    boolean
  • allowed_mcp_tools
    array | null
  • tool_preset
  • precheck_query
    string | null
  • enabled
    boolean
  • emit
    boolean
  • run_interval_minutes
    integer
  • output_destinations
  • network_access
  • auto_pause_exempt
    boolean
  • run_cron_schedule
    string | null
  • display_name
    string
  • skill_name
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/configs
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/signals/scout/configs/\
-d skill_name="string"

Example response

Status 200 A config already existed for this skill; the provided fields were applied to it.
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"skill_name": "string",
"description": "string",
"display_name": "string",
"scout_origin": "canonical",
"scout_role": "specialist",
"deprecation": {
"phase": "announced",
"reason": "string",
"superseded_by": "string",
"sunset_at": "2019-08-24T14:15:22Z"
},
"owners": [
{
"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"
}
],
"enabled": true,
"status": "active",
"pause_reason": "no_output",
"managed_by": "team",
"emit": true,
"run_interval_minutes": 30,
"run_cron_schedule": "string",
"output_destinations": {
"slack": {
"integration_id": 1,
"channel": "string",
"users": [
"string"
],
"thread_reports": true
},
"webhook": {
"hog_function_id": "string"
},
"inbox": true
},
"structured_output_schema": {},
"network_access": "trusted",
"model": "string",
"custom_image_id": "871a86c2-b20e-4ced-8336-55149e45aaf7",
"mcp_gateway_server_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"repositories": [
"string"
],
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"max_report_actions_per_day": 20,
"lifecycle_locked": true,
"allowed_mcp_tools": [
"string"
],
"tool_preset": "string",
"precheck_query": "string",
"precheck_disabled": true,
"effective_precheck_query": "string",
"precheck_query_source": "config",
"last_precheck_at": "2019-08-24T14:15:22Z",
"last_precheck_outcome": "run",
"last_precheck_row_count": 0,
"last_run_at": "2019-08-24T14:15:22Z",
"consecutive_failure_count": 0,
"status_changed_at": "2019-08-24T14:15:22Z",
"status_changed_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"
},
"auto_pause_exempt": true,
"tags": [
"string"
],
"source_product": "string",
"source_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
Status 201 Created config.
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"skill_name": "string",
"description": "string",
"display_name": "string",
"scout_origin": "canonical",
"scout_role": "specialist",
"deprecation": {
"phase": "announced",
"reason": "string",
"superseded_by": "string",
"sunset_at": "2019-08-24T14:15:22Z"
},
"owners": [
{
"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"
}
],
"enabled": true,
"status": "active",
"pause_reason": "no_output",
"managed_by": "team",
"emit": true,
"run_interval_minutes": 30,
"run_cron_schedule": "string",
"output_destinations": {
"slack": {
"integration_id": 1,
"channel": "string",
"users": [
"string"
],
"thread_reports": true
},
"webhook": {
"hog_function_id": "string"
},
"inbox": true
},
"structured_output_schema": {},
"network_access": "trusted",
"model": "string",
"custom_image_id": "871a86c2-b20e-4ced-8336-55149e45aaf7",
"mcp_gateway_server_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"repositories": [
"string"
],
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"max_report_actions_per_day": 20,
"lifecycle_locked": true,
"allowed_mcp_tools": [
"string"
],
"tool_preset": "string",
"precheck_query": "string",
"precheck_disabled": true,
"effective_precheck_query": "string",
"precheck_query_source": "config",
"last_precheck_at": "2019-08-24T14:15:22Z",
"last_precheck_outcome": "run",
"last_precheck_row_count": 0,
"last_run_at": "2019-08-24T14:15:22Z",
"consecutive_failure_count": 0,
"status_changed_at": "2019-08-24T14:15:22Z",
"status_changed_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"
},
"auto_pause_exempt": true,
"tags": [
"string"
],
"source_product": "string",
"source_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
Status 400 No such skill on this project, the name is reserved by the inbox, or the project is already at its enabled-scouts maximum.
Status 403 The caller lacks editor access to skills on this project.

Update signals scout config

Tune one scout: change its schedule (rolling run_interval_minutes, or a cron run_cron_schedule that takes precedence when set), enabled, emit (dry-run) posture, network_access (trusted-domain allowlist vs full access for the scout's sandbox), or output destinations. skill_name is fixed. Enabling records enabled_by and is activity-logged since it drives spend.

Required API key scopes

signal_scout:write

Path parameters

  • id
    string

Request parameters

  • display_name
    string
  • enabled
    boolean
  • emit
    boolean
  • run_interval_minutes
    integer
  • run_cron_schedule
    string | null
  • output_destinations
  • structured_output_schema
    object | null
  • network_access
  • model
    string | null
  • custom_image_id
    string | null
  • auto_pause_exempt
    boolean
  • tags
    array
  • mcp_gateway_server_ids
    array
  • repositories
    array
  • write_scopes
    array
  • report_actions
    array
  • max_report_actions_per_day
    integer
  • precheck_query
    string | null
  • precheck_disabled
    boolean
  • suggestion_id
    string
  • lifecycle_locked
    boolean
  • allowed_mcp_tools
    array | null
  • tool_preset

Response


Example request

PATCH /api/projects/:project_id/signals/scout/configs/: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/signals/scout/configs/:id/\
-d display_name="string"

Example response

Status 200 Updated config.
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"skill_name": "string",
"description": "string",
"display_name": "string",
"scout_origin": "canonical",
"scout_role": "specialist",
"deprecation": {
"phase": "announced",
"reason": "string",
"superseded_by": "string",
"sunset_at": "2019-08-24T14:15:22Z"
},
"owners": [
{
"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"
}
],
"enabled": true,
"status": "active",
"pause_reason": "no_output",
"managed_by": "team",
"emit": true,
"run_interval_minutes": 30,
"run_cron_schedule": "string",
"output_destinations": {
"slack": {
"integration_id": 1,
"channel": "string",
"users": [
"string"
],
"thread_reports": true
},
"webhook": {
"hog_function_id": "string"
},
"inbox": true
},
"structured_output_schema": {},
"network_access": "trusted",
"model": "string",
"custom_image_id": "871a86c2-b20e-4ced-8336-55149e45aaf7",
"mcp_gateway_server_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"repositories": [
"string"
],
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"max_report_actions_per_day": 20,
"lifecycle_locked": true,
"allowed_mcp_tools": [
"string"
],
"tool_preset": "string",
"precheck_query": "string",
"precheck_disabled": true,
"effective_precheck_query": "string",
"precheck_query_source": "config",
"last_precheck_at": "2019-08-24T14:15:22Z",
"last_precheck_outcome": "run",
"last_precheck_row_count": 0,
"last_run_at": "2019-08-24T14:15:22Z",
"consecutive_failure_count": 0,
"status_changed_at": "2019-08-24T14:15:22Z",
"status_changed_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"
},
"auto_pause_exempt": true,
"tags": [
"string"
],
"source_product": "string",
"source_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid fields, or enabling would exceed the project's enabled-scouts maximum.
Status 404 Config not found for this project.

Delete signals scout config

Delete one scout config by its id, removing the per-(team, skill) schedule/emit row outright. The point is cleaning up an orphaned config whose skill was archived or deleted — it lingers in list with an empty description, never runs (the coordinator skips it and the skill can't load), but can't otherwise be removed over the API. Deletion is activity-logged. Note: auto-registration only scans live signals-scout-* skills, so a config deleted for one of those is back on the coordinator's next tick. A scout under any other name does not come back on its own: its config stays deleted until you re-register it, and its skill still reads as a scout meanwhile. To retire a live scout, archive its skill (or set enabled=false to make it inert) rather than deleting the config. A scout whose scout_role is operational cannot be deleted: it is part of the self-driving system rather than the project's own fleet.

Required API key scopes

signal_scout:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/signals/scout/configs/: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/signals/scout/configs/:id/

Example response

Status 204 Config deleted.
Status 400 This scout is operational and cannot be deleted.
Status 404 Config not found for this project.

Create signals scout config precheck

Run a scout's pre-check query once and return its rows, without starting a run and without saving anything. The query gets the same {since} and {now} values the next scheduled run would get, so the result says whether that run would start or skip. Pass precheck_query to try a query before you save it, or omit it to try the effective one: the saved query, or the default the scout's skill ships. A query error comes back in the error field with a 200, because a scheduled run treats it as a reason to run.

Required API key scopes

signal_scout:readquery:read

Path parameters

  • id
    string

Request parameters

  • precheck_query
    string | null

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/precheck_test
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/signals/scout/configs/:id/precheck_test/\
-d precheck_query="string"

Example response

Status 200 What the pre-check returns now, and whether a scheduled run would start.
RESPONSE
{
"would_run": true,
"reason": "rows",
"since": "2019-08-24T14:15:22Z",
"now": "2019-08-24T14:15:22Z",
"interval_minutes": 0,
"row_count": 0,
"columns": [
"string"
],
"rows_text": "string",
"error": "string",
"acting_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"
}
}
Status 400 The scout has no saved pre-check and the request gives no query.
Status 404 Config not found for this project.

Create signals scout config

Dispatch one on-demand run of this scout immediately, regardless of its schedule. Useful to test a scout right after authoring it, or to refresh its findings on demand. The run executes asynchronously on the worker and inherits every guard the scheduled path has: it is forbidden if scouts are not enabled for the project (403), and skipped if self-driving is paused at the project's pull request limit, or the project is over its daily report limit or daily run budget (429), or a run for this scout is already in progress (409). A manual run counts against the same daily run budget as scheduled runs, so repeated manual runs of the same scout can exhaust the project's daily allowance. A manual run does not change the scout's schedule or last_run_at. A disabled scout can still be run this way (to test before enabling). Pass an optional note to steer this one run without leaving a scout note that would steer every later run too. Returns immediately with the workflow id: poll the scout's runs for the result.

Required API key scopes

signal_scout:write

Path parameters

  • id
    string

Request parameters

  • note
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/: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/signals/scout/configs/:id/run/\
-d note="string"

Example response

Status 202 A run was dispatched. It executes asynchronously; poll the scout's runs for the result.
RESPONSE
{
"skill_name": "string",
"workflow_id": "string",
"started": true
}
Status 400 The note is longer than the limit.
Status 403 Signals scouts are not enabled for this project, or the caller may not steer a run with a note.
Status 404 Config not found for this project (or the scout is withheld).
Status 409 A run for this scout is already in progress.
Status 429 Self-driving is paused at the project's pull request limit, or the project is over its daily report limit or its daily scout run budget; try again later.

Create signals scout config

Stop the run of this scout that is in progress now. The run is cancelled the same way as a task run cancel: the agent is interrupted, the sandbox is torn down, and the run is marked cancelled, so the scout can run again. Idempotent: a run that already finished is returned unchanged. Returns 404 when the scout has no run in progress.

Required API key scopes

signal_scout:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/stop
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/signals/scout/configs/:id/stop/

Example response

Status 200 The run finished before the stop reached it. It is returned unchanged.
RESPONSE
{
"total_spend": 0,
"run_id": "string",
"skill_name": "string",
"skill_version": 0,
"status": "not_started",
"created_at": "string",
"started_at": "string",
"completed_at": "string",
"task_id": "string",
"task_run_id": "string",
"task_url": "string",
"summary": "string",
"error": "string",
"failure_reason": "string",
"emitted_count": 0,
"emitted_finding_ids": [
"string"
],
"emitted_report_ids": [
"string"
],
"edited_report_ids": [
"string"
],
"metadata": {
"harness_prompt_version": "string",
"report_channel": "string",
"skill_origin": "string",
"github_guidance": true,
"business_knowledge_maintained": true,
"model": "string",
"runtime_adapter": "string",
"reasoning_effort": "string",
"service_tier": "string",
"network_access": "string",
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"report_action_starts": [
{
"at": "string",
"report_id": "string",
"action": "string"
}
],
"triggered_by": "string",
"run_note": "string",
"derived": {
"has_emit_report": true,
"has_edit_report": true,
"has_self_improvement": true,
"has_chart": true,
"has_self_validation": true,
"has_structured_output": true,
"has_not_in_use_closeout": true
}
}
}
Status 202 The stop was accepted.
RESPONSE
{
"total_spend": 0,
"run_id": "string",
"skill_name": "string",
"skill_version": 0,
"status": "not_started",
"created_at": "string",
"started_at": "string",
"completed_at": "string",
"task_id": "string",
"task_run_id": "string",
"task_url": "string",
"summary": "string",
"error": "string",
"failure_reason": "string",
"emitted_count": 0,
"emitted_finding_ids": [
"string"
],
"emitted_report_ids": [
"string"
],
"edited_report_ids": [
"string"
],
"metadata": {
"harness_prompt_version": "string",
"report_channel": "string",
"skill_origin": "string",
"github_guidance": true,
"business_knowledge_maintained": true,
"model": "string",
"runtime_adapter": "string",
"reasoning_effort": "string",
"service_tier": "string",
"network_access": "string",
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"report_action_starts": [
{
"at": "string",
"report_id": "string",
"action": "string"
}
],
"triggered_by": "string",
"run_note": "string",
"derived": {
"has_emit_report": true,
"has_edit_report": true,
"has_self_improvement": true,
"has_chart": true,
"has_self_validation": true,
"has_structured_output": true,
"has_not_in_use_closeout": true
}
}
}
Status 400 The run is not a cloud run, so it cannot be stopped here.
Status 404 Config not found for this project (or the scout is withheld), or the scout has no run in progress.
Status 503 The stop could not reach the run's workflow. It is safe to try again.

Create signals scout config

Run a prompt, model, or effort variant against live data with private memory and report capture.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Request parameters

  • launch_id
    string
  • context_id
    string
  • variant
    string
  • skill_body
    string
  • model
    string
  • reasoning_effort
    string
  • note
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/trial
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/signals/scout/configs/:id/trial/\
-d launch_id="string"

Example response

Status 202
RESPONSE
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"workflow_id": "string",
"model": "string",
"reasoning_effort": "string",
"variant": "string"
}

Create signals scout config trial comparison

Freeze variants and the reviewed rubric, then run scouts and judge their results in the background.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Request parameters

  • comparison_id
    string
  • baseline_variant_id
    string
  • variants
    Click to open
    array
  • note
    string
  • expected_skill_version
    integer

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/trial_comparison
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/signals/scout/configs/:id/trial_comparison/\
-d comparison_id="string",\
-d baseline_variant_id="string",\
-d variants="array"

Example response

Status 202
RESPONSE
{
"comparison_id": "3b27d395-1e6b-479b-baa5-81329cfca144",
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"rubric_revision": 0,
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string"
}
],
"status": "not_started",
"archived": true,
"error": "string",
"evaluation": {
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}
}

Create signals scout config trial comparison

Hide a finished trial from history or restore it without deleting results or starting any work.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Request parameters

  • comparison_id
    string
  • archived
    boolean

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/trial_comparison_archive
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/signals/scout/configs/:id/trial_comparison_archive/\
-d comparison_id="string",\
-d archived="boolean"

Example response

Status 200
RESPONSE
{
"comparison_id": "3b27d395-1e6b-479b-baa5-81329cfca144",
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"rubric_revision": 0,
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string"
}
],
"status": "not_started",
"archived": true,
"error": "string",
"evaluation": {
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}
}

Retrieve signals scout config trial comparison

Read recent comparisons, including those saved before any scout run started.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • cursor
    string
  • include_archived
    boolean
    Default: false
  • limit
    integer
    Default: 30

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_comparison_history
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_comparison_history/

Example response

Status 200
RESPONSE
{
"results": [
{
"comparison_id": "3b27d395-1e6b-479b-baa5-81329cfca144",
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"rubric_revision": 0,
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string"
}
],
"status": "not_started",
"archived": true,
"error": "string",
"evaluation": {
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}
}
],
"has_more": true,
"next_cursor": "string"
}

Retrieve signals scout config trial comparison

Read comparison progress and its saved report without starting any scout or judge calls.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • comparison_id
    string

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_comparison_result
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_comparison_result/

Example response

Status 200
RESPONSE
{
"comparison_id": "3b27d395-1e6b-479b-baa5-81329cfca144",
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"rubric_revision": 0,
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string"
}
],
"status": "not_started",
"archived": true,
"error": "string",
"evaluation": {
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}
}

Create signals scout config trial comparison

Recover the same comparison without repeating saved scout runs or judge attempts.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Request parameters

  • comparison_id
    string

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/trial_comparison_resume
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/signals/scout/configs/:id/trial_comparison_resume/\
-d comparison_id="string"

Example response

Status 202
RESPONSE
{
"comparison_id": "3b27d395-1e6b-479b-baa5-81329cfca144",
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"rubric_revision": 0,
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string"
}
],
"status": "not_started",
"archived": true,
"error": "string",
"evaluation": {
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}
}

Create signals scout config trial evaluation

Freeze rubric and evidence, then judge explicit variant groups without changing production scouts.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Request parameters

  • evaluation_id
    string
  • baseline_variant_id
    string
  • variants
    Click to open
    array
  • rubric_source

Response


Example request

POST /api/projects/:project_id/signals/scout/configs/:id/trial_evaluation
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/signals/scout/configs/:id/trial_evaluation/\
-d evaluation_id="string",\
-d baseline_variant_id="string",\
-d variants="array",\
-d rubric_source=undefined

Example response

Status 202
RESPONSE
{
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}

Retrieve signals scout config trial evaluation

Read saved scores, criterion evidence and baseline differences without starting model calls.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • evaluation_id
    string

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_evaluation_result
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_evaluation_result/

Example response

Status 200
RESPONSE
{
"request": {
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"variants": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"label": "string",
"launch_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"rubric_source": "saved"
},
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"status": "pending",
"error": "string",
"report": {
"version": 1,
"evaluation_id": "4108ec8e-6efd-4b9b-bace-0bb4c296c324",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"created_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"summary": "string",
"outcome": null,
"rubric_source": "saved",
"rubric_revision": 0,
"rubric_reference_context": null,
"rubric_reference_generation_id": null,
"criteria": [
{
"id": "string",
"title": "string",
"description": "string",
"pass_condition": "string",
"applicability": "string"
}
],
"baseline_variant_id": "d2b87c97-777a-48f8-9766-d8e68e9a46cf",
"judge_model": "string",
"judge_prompt_version": "string",
"variants": [
{
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"label": "string",
"is_baseline": true,
"total_runs": 0,
"judged_runs": 0,
"excluded_runs": 0,
"judge_errors": 0,
"score": 0,
"coverage": 0,
"baseline_delta": null,
"criteria": [
{
"criterion_id": "string",
"passed": 0,
"failed": 0,
"unknown": 0,
"not_applicable": 0,
"pass_rate": 0,
"coverage": 0,
"baseline_delta": null
}
]
}
],
"runs": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"status": "judged",
"score": null,
"coverage": null,
"summary": "string",
"criteria": [
{
"criterion_id": "string",
"verdict": "pass",
"reason": "string",
"confidence": "low",
"evidence": [
{
"source_id": "string",
"quote": "string"
}
]
}
],
"error": null,
"input_tokens": null,
"output_tokens": null
}
],
"evidence": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"variant_id": "8a2d415d-59aa-4132-bef3-011f97c4a0f6",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"execution_status": "string",
"exclusion_reason": null,
"model": "string",
"runtime_adapter": "claude",
"service_tier": null,
"reasoning_effort": "string",
"skill_body_sha256": "string",
"input_tokens": null,
"output_tokens": null,
"files": [
{
"id": "string",
"kind": "instructions",
"filename": "string",
"sha256": "string",
"size_bytes": 0
}
],
"sources": [
{
"id": "string",
"kind": "instructions",
"text": "string"
}
],
"limitations": [
"string"
]
}
],
"limitations": [
"string"
]
}
}

Retrieve signals scout config trial

Read recent private runs for the requesting operator in the internal comparison editor.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • limit
    integer
    Default: 30

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_history
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_history/

Example response

Status 200
RESPONSE
{
"results": [
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"variant": "string",
"model": "string",
"reasoning_effort": "string",
"status": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b"
}
],
"has_more": true
}

Retrieve signals scout config trial

Read a trial's existing run status and its privately captured reports and memory changes.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • launch_id
    string

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_result
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_result/

Example response

Status 200
RESPONSE
{
"launch_id": "e84bcd27-699d-48e8-b842-1ce01401cf1f",
"context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
"model": "string",
"reasoning_effort": "string",
"skill_body_sha256": "string",
"result_key": "string",
"export_error": "string",
"started_at": "2019-08-24T14:15:22Z",
"completed_at": "2019-08-24T14:15:22Z",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"task_id": "736fde4d-9029-4915-8189-01353d6982cb",
"task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
"status": "string",
"task_status": "string",
"error": "string",
"summary": "string",
"invalid_reason": "string",
"reports": [
{
"id": "string",
"source_report_id": null,
"document": {
"property1": null,
"property2": null
},
"payload": {
"property1": null,
"property2": null
},
"edits": [
{
"property1": null,
"property2": null
}
],
"operator_metadata": {
"property1": null,
"property2": null
},
"evidence": [
{
"property1": null,
"property2": null
}
],
"artefacts": [
{
"property1": null,
"property2": null
}
],
"content_revision_count": 0,
"corroboration_count": 0
}
],
"memory": {
"property1": {
"key": "string",
"content": "string",
"created_at": "string",
"updated_at": "string",
"expires_at": "string",
"created_by_run_id": "string",
"created_by_skill": "string",
"created_by_run_url": "string",
"revisions": [
{
"content": "string",
"expires_at": "string",
"change": "overwrite",
"changed_at": "string",
"changed_by_run_id": "string",
"changed_by_skill": "string",
"changed_by_run_url": "string"
}
],
"expired": true,
"last_changed_by_skill": "string",
"last_changed_at": "string",
"revived_expiry": {
"expires_at": "string",
"set_by_skill": "string",
"set_at": "string"
}
},
"property2": {
"key": "string",
"content": "string",
"created_at": "string",
"updated_at": "string",
"expires_at": "string",
"created_by_run_id": "string",
"created_by_skill": "string",
"created_by_run_url": "string",
"revisions": [
{
"content": "string",
"expires_at": "string",
"change": "overwrite",
"changed_at": "string",
"changed_by_run_id": "string",
"changed_by_skill": "string",
"changed_by_run_url": "string"
}
],
"expired": true,
"last_changed_by_skill": "string",
"last_changed_at": "string",
"revived_expiry": {
"expires_at": "string",
"set_by_skill": "string",
"set_at": "string"
}
}
},
"cost_usd": 0,
"input_tokens": 0,
"output_tokens": 0
}

Retrieve signals scout config trial

Read comparison readiness and source settings for the internal comparison editor.

Required API key scopes

signal_scout:writellm_skill:write

Path parameters

  • id
    string

Query parameters

  • context_id
    string

Response


Example request

GET /api/projects/:project_id/signals/scout/configs/:id/trial_setup
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/signals/scout/configs/:id/trial_setup/

Example response

Status 200
RESPONSE
{
"config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
"skill_name": "string",
"skill_version": 0,
"skill_body": "string",
"ready": true,
"blocked_reason": "string",
"model": "string",
"reasoning_effort": "string",
"models": [
{
"model": "string",
"reasoning_efforts": [
"string"
]
}
]
}

Create signals scout config

Materialize the scout fleet for this project on demand (idempotent): seed the canonical signals-scout-* skills, create a default-schedule config for any scout lacking one, retire the skills whose canonical scout no longer ships, and return all scout configs. Normally the Temporal coordinator does this on its next tick; this action exists so the scout UIs and setup flows (e.g. the wizard's self-driving program) can hand the user a tunable fleet immediately. With surface=onboarding, new configs stay disabled until explicitly activated.

Required API key scopes

signal_scout:write

Query parameters

  • surface
    string
    One of: "roster""desktop""wizard""onboarding"

Example request

POST /api/projects/:project_id/signals/scout/configs/sync
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/signals/scout/configs/sync/

Example response

Status 200 The team's full scout fleet after the sync, ordered by skill name.
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"skill_name": "string",
"description": "string",
"display_name": "string",
"scout_origin": "canonical",
"scout_role": "specialist",
"deprecation": {
"phase": "announced",
"reason": "string",
"superseded_by": "string",
"sunset_at": "2019-08-24T14:15:22Z"
},
"owners": [
{
"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"
}
],
"enabled": true,
"status": "active",
"pause_reason": "no_output",
"managed_by": "team",
"emit": true,
"run_interval_minutes": 30,
"run_cron_schedule": "string",
"output_destinations": {
"slack": {
"integration_id": 1,
"channel": "string",
"users": [
"string"
],
"thread_reports": true
},
"webhook": {
"hog_function_id": "string"
},
"inbox": true
},
"structured_output_schema": {},
"network_access": "trusted",
"model": "string",
"custom_image_id": "871a86c2-b20e-4ced-8336-55149e45aaf7",
"mcp_gateway_server_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"repositories": [
"string"
],
"write_scopes": [
"string"
],
"report_actions": [
"string"
],
"max_report_actions_per_day": 20,
"lifecycle_locked": true,
"allowed_mcp_tools": [
"string"
],
"tool_preset": "string",
"precheck_query": "string",
"precheck_disabled": true,
"effective_precheck_query": "string",
"precheck_query_source": "config",
"last_precheck_at": "2019-08-24T14:15:22Z",
"last_precheck_outcome": "run",
"last_precheck_row_count": 0,
"last_run_at": "2019-08-24T14:15:22Z",
"consecutive_failure_count": 0,
"status_changed_at": "2019-08-24T14:15:22Z",
"status_changed_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"
},
"auto_pause_exempt": true,
"tags": [
"string"
],
"source_product": "string",
"source_id": "string",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}