Signals

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

Endpoints

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

List all signals scout report check

Every check on one report, newest first. The report_id is the only input. Read this before writing one: a report already carrying a check for the same claim needs no second one, and a report holds at most five open checks at a time.

Required API key scopes

signal_scout_report:write

Query parameters

  • report_id
    string

Example request

GET /api/projects/:project_id/signals/scout/runs/report-checks
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/report-checks/

Example response

Status 200 The report's checks, newest first.
RESPONSE
{
"check_id": "051490c8-9abf-480a-9348-72c146208cd5",
"report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
"title": "string",
"kind": "string",
"status": "string",
"next_run_at": "2019-08-24T14:15:22Z",
"last_outcome": "string",
"last_outcome_reason": "string",
"run_state": "string",
"waiting_on_run": true,
"dispatched_run_id": "0d40720c-3ac9-4b33-96ee-ba348f818515",
"dispatched_at": "2019-08-24T14:15:22Z"
}
Status 400 The report does not exist for this project.

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, and skill_name to keep the entries one scout (or pipeline:* stage) created. 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. Entries whose expires_at has passed are excluded unless include_expired=true, and are hard-deleted by a daily janitor once their expiry is more than two weeks in the past. 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
  • include_expired
    boolean
    Default: false
  • key
    string
  • keys_only
    boolean
  • limit
    integer
  • skill_name
    string
  • 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/

Example response

Status 200 Matching memory entries newest-first.
RESPONSE
{
"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"
}

Create signals scout scratchpad

Upsert a memory keyed on (team, key). Re-using a key updates the existing entry in place. A write carries the entry's whole state, so expires_at is set when passed and cleared when omitted.

Required API key scopes

signal_scratchpad_internal:write

Request parameters

  • key
    string
  • content
    string
  • run_id
    string | null
  • expires_at
    string | null

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"

Example response

Status 200 Memory entry written or refreshed.
RESPONSE
{
"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"
}
Status 400 Invalid memory shape (empty key/content, key too long, or an `expires_at` on a `followup:` entry). An unparseable or past `expires_at` is dropped, not rejected.

Create signals scout scratchpad

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

Required API key scopes

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

Example response

Status 200 Whether a row was removed.
RESPONSE
{
"deleted": true
}

List all signals scout suggestions

Return the pre-computed scout suggestions for this project: up to five picks, best first, each either a PostHog-authored scout to turn on or a drafted custom scout. Dismissed and already-created suggestions are omitted. An empty items with status empty means no batch has been generated yet; the interactive scout-chat-tasks path still works.

Required API key scopes

signal_scout:read

Response


Example request

GET /api/projects/:project_id/signals/scout/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/signals/scout/suggestions/

Example response

Status 200 The current batch.
RESPONSE
{
"status": "fresh",
"generated_at": "2019-08-24T14:15:22Z",
"model": "string",
"fleet_snapshot": [
"string"
],
"items": [
{
"id": "string",
"kind": "canonical",
"skill_name": "string",
"title": "string",
"why_here": "string",
"description": "string",
"draft_body": "string",
"proposed_config": {
"run_cron_schedule": "string",
"run_interval_minutes": 0,
"emit": true
},
"gap": true,
"confidence": "low"
}
]
}

Create signals scout suggestions

Hide one suggestion from this project's batch. Dismissal is remembered across refreshes by skill name, so the same suggestion is not shown again.

Required API key scopes

signal_scout:write

Path parameters

  • id
    string

Response


Example request

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

Example response

Status 200 The dismissed suggestion.
RESPONSE
{
"id": "string",
"kind": "canonical",
"skill_name": "string",
"title": "string",
"why_here": "string",
"description": "string",
"draft_body": "string",
"proposed_config": {
"run_cron_schedule": "string",
"run_interval_minutes": 0,
"emit": true
},
"gap": true,
"confidence": "low"
}
Status 404 No suggestion with that id in this project's batch.

Create signals scout suggestions

Re-run the suggestion scan for this project now instead of waiting for the scheduled refresh. Runs headlessly; poll the list endpoint for the new batch (generated_at advances). Capped per project per day.

Required API key scopes

signal_scout:write

Response


Example request

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

Example response

Status 202 Refresh dispatched.
RESPONSE
{
"workflow_id": "string"
}
Status 403 Organization has not approved AI data processing, or suggestions are off for this project.
Status 409 A refresh is already running for this project.
Status 429 Daily refresh cap reached.

List all signals source configs

Required API key scopes

inbox: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/

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": {},
"config_set": {},
"config_remove": [
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"status": "running"
}
]
}

Create signals source configs

Required API key scopes

inbox:write

Request parameters

  • source_product
  • source_type
  • enabled
    boolean
  • config
    object
  • config_set
    object
  • config_remove
    array

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

Example response

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

Retrieve signals source configs

Required API key scopes

inbox: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/

Example response

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

Update signals source configs

Required API key scopes

inbox:write

Path parameters

  • id
    string

Request parameters

  • source_product
  • source_type
  • enabled
    boolean
  • config
    object
  • config_set
    object
  • config_remove
    array

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

Example response

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

Delete signals source configs

Required API key scopes

inbox: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/

Example response

Status 204 No response body

Create signals source configs alert pattern preview

Check allow and block patterns for the product analytics source before saving them. Returns why each list would be rejected, and what the patterns do to the project's enabled alerts: which ones they let through and which ones they drop. Saves nothing.

Required API key scopes

inbox:read

Request parameters

  • alert_allow_patterns
    array
  • alert_block_patterns
    array

Response


Example request

POST /api/projects/:project_id/signals/source_configs/alert_pattern_preview
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/alert_pattern_preview/\
-d alert_allow_patterns="array"

Example response

Status 200
RESPONSE
{
"alert_allow_patterns_error": "string",
"alert_block_patterns_error": "string",
"alerts": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"insight_name": "string",
"insight_short_id": "string",
"outcome": "passed"
}
],
"has_more": true
}

Retrieve signals source

Required API key scopes

signal_usage:read

Example request

GET /api/projects/:project_id/signals/source_spend
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_spend/

Example response

Status 200
RESPONSE
{
"source_product": "string",
"source_type": "string",
"signal_count": 0,
"spend": {
"total_spend": 0,
"incomplete": true
}
}

Retrieve signals spend

Required API key scopes

signal_usage:read

Response


Example request

GET /api/projects/:project_id/signals/spend
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/spend/

Example response

Status 200
RESPONSE
{
"period_start": "2019-08-24T14:15:22Z",
"period_end": "2019-08-24T14:15:22Z",
"scouts": [
{
"skill_name": "string",
"spend": {
"total_spend": 0,
"incomplete": true
},
"average_spend": 0
}
],
"scout_spend": {
"total_spend": 0,
"incomplete": true
}
}

List all signals trial

Required API key scopes

project:read

Response


Example request

GET /api/projects/:project_id/signals/trial
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/trial/

Example response

Status 200
RESPONSE
{
"enabled": true,
"flag_confirmed": true,
"policy_version": 0,
"legacy_pr_restricted": true,
"billing_ready": true,
"eligible": true,
"can_activate": true,
"organization_grants_remaining": 0,
"grant_id": "a3c1da8e-13c6-4cab-955b-2120b58c2982",
"grant_status": "not_claimed",
"exhaustion_reason": "string",
"reports_delivered": 0,
"reports_in_progress": 0,
"report_limit": 0,
"allowance_microusd": 0,
"used_microusd": 0,
"new_work_paused": true,
"enabled_scouts": 0,
"scout_limit": 0,
"scouts_to_pause": 0,
"paid_continuation": "continue_paid"
}

Create signals trial

Required API key scopes

project:write

Response


Example request

POST /api/projects/:project_id/signals/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/trial/

Example response

Status 201
RESPONSE
{
"enabled": true,
"flag_confirmed": true,
"policy_version": 0,
"legacy_pr_restricted": true,
"billing_ready": true,
"eligible": true,
"can_activate": true,
"organization_grants_remaining": 0,
"grant_id": "a3c1da8e-13c6-4cab-955b-2120b58c2982",
"grant_status": "not_claimed",
"exhaustion_reason": "string",
"reports_delivered": 0,
"reports_in_progress": 0,
"report_limit": 0,
"allowance_microusd": 0,
"used_microusd": 0,
"new_work_paused": true,
"enabled_scouts": 0,
"scout_limit": 0,
"scouts_to_pause": 0,
"paid_continuation": "continue_paid"
}

Retrieve signals monthly

Required API key scopes

signal_usage:read

Query parameters

  • month
    string

Response


Example request

GET /api/projects/:project_id/signals/usage
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/usage/

Example response

Status 200
RESPONSE
{
"total_credits": "string",
"exempt_credits": "string",
"incomplete": true,
"project_id": 0,
"period_start": "2019-08-24T14:15:22Z",
"period_end": "2019-08-24T14:15:22Z",
"as_of": "2019-08-24T14:15:22Z",
"unsettled_credits": "string",
"untracked_scout_run_count": 0,
"attribution_incomplete": true,
"sources": [
{
"total_credits": "string",
"exempt_credits": "string",
"incomplete": true,
"source_product": "string",
"source_type": "string",
"processing_credits": "string",
"research_credits": "string",
"implementation_credits": "string"
}
],
"scouts": [
{
"total_credits": "string",
"exempt_credits": "string",
"incomplete": true,
"scout_config_id": "a7f1f72e-887b-40bd-87ff-6cc47df7bea0",
"skill_name": "string",
"display_name": "string",
"run_count": 0,
"reports_produced": 0
}
],
"pricing": {
"currency": "string",
"usd_per_credit": "string"
}
}