Signals

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

Endpoints

GET
PATCH
DELETE
POST
GET
POST
GET
GET
GET
POST
GET

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",
"filter_status": {
"state": "ok",
"error_code": "string",
"error_message": "string",
"failed_at": "2019-08-24T14:15:22Z",
"unread_since": "2019-08-24T14:15:22Z",
"last_success_at": "2019-08-24T14:15:22Z",
"malformed_count": 0
}
}

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",
"filter_status": {
"state": "ok",
"error_code": "string",
"error_message": "string",
"failed_at": "2019-08-24T14:15:22Z",
"unread_since": "2019-08-24T14:15:22Z",
"last_success_at": "2019-08-24T14:15:22Z",
"malformed_count": 0
}
}

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 configs filter catalogs

List the sources whose filter this project can set, each with the fields a filter expression can use and example expressions. A filter is a boolean expression saved in a source config's config.hogql_filter. It excludes records before any AI processing. Available before the source is connected or synced.

Required API key scopes

inbox:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
"results": [
{
"source_product": "string",
"source_type": "string",
"catalog_version": 0,
"filter_fields": [
{
"name": "string",
"type": "string",
"description": "string"
}
],
"starter_expressions": [
"string"
]
}
]
}

Create signals source configs filter preview

Check a filter expression before saving it, and see what it does to the source's records created in the last 7 days: how many pass and how many it excludes, with the newest of each. Reads the records emission would read, with the source's saved team allowlist, and runs with your own warehouse access. Records that pass can still be skipped later by guidance or deduplication. Saves nothing and calls no AI.

Required API key scopes

inbox:readquery:read

Request parameters

  • source_product
    string
  • source_type
    string
  • expression
    string

Response


Example request

POST /api/projects/:project_id/signals/source_configs/filter_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/filter_preview/\
-d source_product="string",\
-d source_type="string",\
-d expression="string"

Example response

Status 200
RESPONSE
{
"status": "ok",
"error": "string",
"catalog_version": 0,
"lookback_days": 0,
"total_count": 0,
"passing_count": 0,
"excluded_count": 0,
"malformed_count": 0,
"passing": [
{
"id": "string",
"identifier": "string",
"title": "string",
"url": "string",
"created_at": "2019-08-24T14:15:22Z",
"malformed": true,
"field_values": {
"property1": "string",
"property2": "string"
}
}
],
"excluded": [
{
"id": "string",
"identifier": "string",
"title": "string",
"url": "string",
"created_at": "2019-08-24T14:15:22Z",
"malformed": true,
"field_values": {
"property1": "string",
"property2": "string"
}
}
]
}

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