Signals-2 API Reference

Signals-2

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

Endpoints

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

← Previous page

Retrieve signals scout runs

Return the full SignalScoutRun row. Status, timing, and error flow from the linked tasks.TaskRun. Strictly team-scoped — a UUID belonging to another team returns 404.

Required API key scopes

signal_scout:read

Path parameters

run_id
string

Response

Example request

GET /api/projects/:project_id/signals/scout/runs/:run_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/signals/scout/runs/:run_id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/scout/runs/{run_id}/".format(
        project_id=project_id,
		run_id="<the run id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Full run detail.

RESPONSE
{
  "run_id": "string",
  "skill_name": "string",
  "skill_version": 0,
  "status": "string",
  "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"
  ]
}

Status 404 Run not found or not visible to this project.

Retrieve signals scout runs

Return the findings a SignalScoutRun emitted to the inbox, newest first — one row per emit with its description (the finding text as surfaced), weight, confidence, severity, and the deterministic source_id that joins back to the underlying signal. Lets a team and its agents see what a run surfaced without parsing emitted_finding_ids or scanning the signal store. Strictly team-scoped — a run UUID belonging to another team returns 404.

Required API key scopes

signal_scout:read

Path parameters

run_id
string

Example request

GET /api/projects/:project_id/signals/scout/runs/:run_id/emissions
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/runs/:run_id/emissions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/scout/runs/{run_id}/emissions/".format(
        project_id=project_id,
		run_id="<the run id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Findings this run emitted to the inbox, newest first.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "run_id": "string",
  "finding_id": "string",
  "description": "string",
  "weight": 1,
  "confidence": 1,
  "severity": "P0",
  "tags": [
    "string"
  ],
  "source_id": "string",
  "emitted_at": "2019-08-24T14:15:22Z"
}

Status 404 Run not found or not visible to this project.

Retrieve signals scout runs emission

Best-effort reverse of the report -> signals link. For each finding the run emitted, resolve the inbox SignalReport (if any) its underlying signal grouped into by walking the deterministic source_id back through the signal store. report is null when the finding hasn't grouped into a report yet, was de-duplicated away, or its signal was deleted. Lets the scout UI surface which inbox report a finding contributed to — the reverse of the report's evidence list. Strictly team-scoped — a run UUID belonging to another team returns 404.

Required API key scopes

signal_scout:readtask:read

Path parameters

run_id
string

Example request

GET /api/projects/:project_id/signals/scout/runs/:run_id/emissions/reports
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/runs/:run_id/emissions/reports/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/scout/runs/{run_id}/emissions/reports/".format(
        project_id=project_id,
		run_id="<the run id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Per-finding inbox report links for this run, newest finding first.

RESPONSE
{
  "finding_id": "string",
  "source_id": "string",
  "report": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "status": "string"
  }
}

Status 404 Run not found or not visible to this project.

Create signals scout emit

Fire emit_signal with source_product = signals_scout. The finding_id is baked into the deterministic Signal.source_id = run:<id>:finding:<id> for traceability, but this is NOT idempotent — a second call with the same finding_id emits a second signal, so do not retry an emit that may have already succeeded.

Required API key scopes

signal_scout_internal:write

Path parameters

run_id
string

Request parameters

description
string
confidence
number
evidence
array
hypothesis
stringnull
severity
dedupe_keys
array
tags
array
time_range
mcp_trace_id
stringnull
finding_id
stringnull

Response

Example request

POST /api/projects/:project_id/signals/scout/runs/:run_id/emit-signal
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/runs/:run_id/emit-signal/\
	-d description="string",\
	-d confidence="number",\
	-d evidence="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/signals/scout/runs/{run_id}/emit-signal/".format(
        project_id=project_id,
		run_id="<the run id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"description": "string",
		"confidence": "number",
		"evidence": "array"
	}
).json()

Example response

Status 200 Finding emitted, or skipped by a preflight gate.

RESPONSE
{
  "finding_id": "string",
  "emitted": true,
  "skipped_reason": "string"
}

Status 400 Invalid emit shape (description, weight, confidence, evidence cap).

Status 404 Run not found for this project.

Retrieve signals scout scratchpad

Return SignalScratchpad entries for this project. ILIKE matches on content and key. Pass keys_only=true to scan keys without pulling entry bodies, or content_max_chars to cap each content to a preview — both keep a wide orientation scan from returning every entry's full prose.

Required API key scopes

signal_scout:read

Query parameters

content_max_chars
integer
keys_only
boolean
limit
integer
text
string

Example request

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

Example response

Status 200 Matching memory entries newest-first.

RESPONSE
{
  "key": "string",
  "content": "string",
  "created_at": "string",
  "updated_at": "string",
  "created_by_run_id": "string"
}

Create signals scout scratchpad

Upsert a memory keyed on (team, key). Re-using a key updates the existing entry in place.

Required API key scopes

signal_scout_internal:write

Request parameters

key
string
content
string
run_id
stringnull

Response

Example request

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

Example response

Status 200 Memory entry written or refreshed.

RESPONSE
{
  "key": "string",
  "content": "string",
  "created_at": "string",
  "updated_at": "string",
  "created_by_run_id": "string"
}

Status 400 Invalid memory shape (empty key/content, key too long).

Create signals scout scratchpad

Delete an entry by key. Returns deleted=false if no row matched.

Required API key scopes

signal_scout_internal:write

Request parameters

key
string

Response

Example request

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

Example response

Status 200 Whether a row was removed.

RESPONSE
{
  "deleted": true
}

List all signals source configs

Required API key scopes

task:read

Query parameters

limit
integer
offset
integer

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "source_product": "session_replay",
      "source_type": "session_analysis_cluster",
      "enabled": true,
      "config": null,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "status": "string"
    }
  ]
}

Create signals source configs

Required API key scopes

task:write

Request parameters

source_product
source_type
enabled
boolean
config

Response

Example request

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

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_product": "session_replay",
  "source_type": "session_analysis_cluster",
  "enabled": true,
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "status": "string"
}

Retrieve signals source configs

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_product": "session_replay",
  "source_type": "session_analysis_cluster",
  "enabled": true,
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "status": "string"
}

Update signals source configs

Required API key scopes

task:write

Path parameters

id
string

Request parameters

source_product
source_type
enabled
boolean
config

Response

Example request

PATCH /api/projects/:project_id/signals/source_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/source_configs/:id/\
	-d source_product=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/signals/source_configs/{signals-2_id}/".format(
        project_id=project_id,
		signals-2_id="<the signals-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source_product": "session_replay",
  "source_type": "session_analysis_cluster",
  "enabled": true,
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "status": "string"
}

Delete signals source configs

Required API key scopes

task:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/signals/source_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/source_configs/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/signals/source_configs/{signals-2_id}/".format(
        project_id=project_id,
		signals-2_id="<the signals-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

← Previous page