Signals API Reference

Signals

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

Endpoints

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

← Previous page

Retrieve signals scout runs recent

Return the team's recently emitted scout findings across every run, newest first — the cross-run counterpart to the per-run emissions action. Each row carries its run_id, so you can regroup by run without first listing runs and fanning out one emissions call each. Pass skill_name to scope to a single scout, and date_from / date_to (a half-open window on emitted_at) to bound or paginate — set date_to to the oldest emission's emitted_at to walk back past the limit. Pure Postgres, no ClickHouse round-trip. Capped at 200 rows (default 50).

Required API key scopes

signal_scout:read

Query parameters

date_from
string
date_to
string
limit
integer
skill_name
string

Example request

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

Example response

Status 200 Recent emitted findings across every run on the team, 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"
}

Create signals scout runs emission reports

Batched form of the per-run emission-reports endpoint. For every finding the requested runs emitted, resolve the inbox SignalReport (if any) its signal grouped into — all in a single ClickHouse round-trip rather than one query per run, which is what made the findings page slow to open. report is null when a finding hasn't grouped yet, was de-duplicated, or its signal was deleted. Strictly team-scoped — run ids belonging to another team contribute no rows.

Required API key scopes

signal_scout:readtask:read

Request parameters

run_ids
array

Example request

POST /api/projects/:project_id/signals/scout/runs/emissions/reports/batch
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/emissions/reports/batch/\
	-d run_ids="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/emissions/reports/batch/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"run_ids": "array"
	}
).json()

Example response

Status 200 Per-finding inbox report links across all requested runs, newest finding first.

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

Retrieve signals scout runs findings

Return a cheap fleet-wide tally of the output the scout troop produced in the recent window — the finding count, the distinct reports authored/edited via the report channel, the number of distinct scouts behind them, and the latest output time. Backs the 'Scout findings' callout so it renders from one query instead of the client paging through the whole runs window. Counts runs that emitted at least one finding (emitted_count > 0) or authored/edited an inbox report within the last window_hours (default 72), capped to the most recent 120 such runs so the count matches what the findings list renders. Strictly team-scoped.

Required API key scopes

signal_scout:read

Query parameters

window_hours
integer

Response

Example request

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

Example response

Status 200 Fleet-wide tally of recent scout output — findings and report activity.

RESPONSE
{
  "count": 0,
  "scout_count": 0,
  "authored_report_count": 0,
  "edited_report_count": 0,
  "latest_at": "2019-08-24T14:15:22Z"
}

Retrieve signals scout scratchpad

Return SignalScratchpad entries for this project, newest-first. ILIKE matches on content and key; pass key instead for an exact single-entry lookup. date_from / date_to are a half-open window on updated_at (>= date_from, < date_to); pass date_to (the updated_at of the oldest entry seen) on subsequent calls to walk past the cap. 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. Results capped at 1000.

Required API key scopes

signal_scout:read

Query parameters

content_max_chars
integer
date_from
string
date_to
string
key
string
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",
  "created_by_skill": "string",
  "created_by_run_url": "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",
  "created_by_skill": "string",
  "created_by_run_url": "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-3_id}/".format(
        project_id=project_id,
		signals-3_id="<the signals-3 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-3_id}/".format(
        project_id=project_id,
		signals-3_id="<the signals-3 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-3_id}/".format(
        project_id=project_id,
		signals-3_id="<the signals-3 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

← Previous page

Signals

Endpoints

Retrieve signals scout runs recent

Required API key scopes

Query parameters

Example request

Example response

Status 200 Recent emitted findings across every run on the team, newest first.

Create signals scout runs emission reports

Required API key scopes

Request parameters

Example request

Example response

Status 200 Per-finding inbox report links across all requested runs, newest finding first.

Retrieve signals scout runs findings

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200 Fleet-wide tally of recent scout output — findings and report activity.

Retrieve signals scout scratchpad

Required API key scopes

Query parameters

Example request

Example response

Status 200 Matching memory entries newest-first.

Create signals scout scratchpad

Required API key scopes

Request parameters

Response

Example request

Example response

Status 200 Memory entry written or refreshed.

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

Create signals scout scratchpad

Required API key scopes

Request parameters

Response

Example request

Example response

Status 200 Whether a row was removed.

List all signals source configs

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create signals source configs

Required API key scopes

Request parameters

Response

Example request

Example response

Status 201

Retrieve signals source configs

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Update signals source configs

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete signals source configs

Required API key scopes

Path parameters

Example request

Example response

Status 204 No response body

Community questions