Signals API Reference

Signals

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

Endpoints

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

List all signals processing

Return current processing state including pause status.

Required API key scopes

task:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/signals/processing
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/processing/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/processing/".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": [
    {
      "paused_until": "2019-08-24T14:15:22Z"
    }
  ]
}

Delete signals processing pause

View and control signal processing pipeline state for a team.

Required API key scopes

task:write

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "status": "string",
  "paused_until": "2019-08-24T14:15:22Z"
}

List all signals reports

Required API key scopes

task:read

Query parameters

has_implementation_pr
boolean
limit
integer
offset
integer
ordering
string
priority
string
search
string
source_product
string
status
string
suggested_reviewers
string
task_id
string

Response

Example request

GET /api/projects/:project_id/signals/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/reports/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/reports/".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",
      "title": "string",
      "summary": "string",
      "status": "potential",
      "total_weight": 0.1,
      "signal_count": 0,
      "signals_at_run": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "artefact_count": 0,
      "priority": "string",
      "actionability": "string",
      "already_addressed": true,
      "dismissal_reason": "string",
      "dismissal_note": "string",
      "is_suggested_reviewer": false,
      "source_products": [
        "string"
      ],
      "implementation_pr_url": "string"
    }
  ]
}

Retrieve signals reports

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "summary": "string",
  "status": "potential",
  "total_weight": 0.1,
  "signal_count": 0,
  "signals_at_run": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "artefact_count": 0,
  "priority": "string",
  "actionability": "string",
  "already_addressed": true,
  "dismissal_reason": "string",
  "dismissal_note": "string",
  "is_suggested_reviewer": false,
  "source_products": [
    "string"
  ],
  "implementation_pr_url": "string"
}

Create signals reports state

Transition a report to a new state. The model validates allowed transitions.

The request body is validated by SignalReportStateRequestSerializer — only the fields it declares (state, dismissal_reason, dismissal_note, snooze_for) are read, and only snooze_for is ever forwarded to transition_to. Any other key is ignored, so internal transition_to kwargs (reset_weight, error, ...) can't be injected.

Body: { "state": "suppressed" | "potential", # Optional dismissal feedback (honored when state == "suppressed" or "potential"): "dismissal_reason": "<canonical reason code, see SIGNAL_REPORT_DISMISSAL_REASON_CHOICES>", "dismissal_note": "free-form text", # Optional, only honored for state == "potential": "snooze_for": <number of additional signals before re-promotion>, }

Required API key scopes

task:write

Path parameters

id
string

Request parameters

state
dismissal_reason
dismissal_note
string
snooze_for
integer

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "summary": "string",
  "status": "potential",
  "total_weight": 0.1,
  "signal_count": 0,
  "signals_at_run": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "artefact_count": 0,
  "priority": "string",
  "actionability": "string",
  "already_addressed": true,
  "dismissal_reason": "string",
  "dismissal_note": "string",
  "is_suggested_reviewer": false,
  "source_products": [
    "string"
  ],
  "implementation_pr_url": "string"
}

List all signals report artefacts

List every artefact on a report — the full work log: signal findings (the evidence behind the report), status judgments (safety / actionability / priority, repo selection, suggested reviewers — the newest row of each status type is canonical), and log entries (code references, commits, task runs, notes). suggested_reviewers content is enriched with PostHog user info at read time.

Required API key scopes

task:read

Path parameters

report_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/signals/reports/:report_id/artefacts
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/reports/:report_id/artefacts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/signals/reports/{report_id}/artefacts/".format(
        project_id=project_id,
		report_id="<the report 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",
      "type": "video_segment",
      "content": {},
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com"
      },
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
    }
  ]
}

Create signals report artefacts

Append an artefact to a report (see artefact_type for the writable types). Everything is append-only: log entries (code reference, commit, task run, note) accumulate, while status types (safety / actionability / priority judgments, repo selection, suggested reviewers) are latest-wins — appending a new version supersedes the previous one as the report's canonical status. Content is validated against the type's schema.

Required API key scopes

task:write

Path parameters

report_id
string

Request parameters

artefact_type
string
content

Response

Example request

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

Example response

Status 201 Artefact created.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
  "type": "string",
  "content": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}

Status 400 Unknown artefact type, content not matching the type's schema, or an invalid X-PostHog-Task-Id header.

Status 404 Report not found for this project.

Retrieve signals report artefacts

Get one artefact by id, content parsed (and reviewers enriched) the same way as the list.

Required API key scopes

task:read

Path parameters

id
string
report_id
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "type": "video_segment",
  "content": {},
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com"
  },
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}

Update signals report artefacts

Replace the content of an existing artefact, addressed by id. The new content is validated against the artefact's type schema. Editing the latest row of a status type changes the report's canonical status (latest-wins); to re-assess while keeping history, append a new artefact instead. Attribution is creation-time only — edits don't reassign it.

Required API key scopes

task:write

Path parameters

id
string
report_id
string

Request parameters

content

Response

Example request

PATCH /api/projects/:project_id/signals/reports/:report_id/artefacts/: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/reports/:report_id/artefacts/:id/\
	-d content=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/signals/reports/{report_id}/artefacts/{signal_id}/".format(
        project_id=project_id,
		signal_id="<the signal id>",
		report_id="<the report id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200 Artefact updated.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
  "type": "string",
  "content": null,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
}

Status 400 Content does not match the artefact type's schema.

Status 404 Artefact not found for this report / project.

Delete signals report artefacts

Delete an artefact, addressed by id. Deleting the latest row of a status type reverts the report's canonical status to the previous version (latest-wins over what remains).

Required API key scopes

task:write

Path parameters

id
string
report_id
string

Example request

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

Example response

Status 204 Artefact deleted.

Status 404 Artefact not found for this report / project.

Retrieve signals report artefacts

Fetch the unified diff of a commit artefact's branch against the repository default branch via the team's GitHub integration — using the branch's current tip so the diff reflects the latest state of the work, not just the single recorded commit.

Required API key scopes

task:read

Path parameters

id
string
report_id
string

Response

Example request

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

Example response

Status 200 The branch's unified diff against the repository default branch.

RESPONSE
{
  "diff": "string",
  "truncated": true
}

Status 400 Artefact is not a commit, or is missing repository/branch.

Status 404 Artefact not found, or no GitHub integration can access the repository.

Status 502 GitHub could not produce the diff (branch not found, fetch failed).

Create signals reports bulk state

Transition many reports to a new state in one call.

Each id is processed independently: a report whose transition isn't allowed from its current status is reported as skipped (a 409 on the single-report endpoint) and the rest still go through. Returns one result per requested id (in request order, after de-duplication) plus per-outcome counts. The whole call is 200 even on partial failure — inspect results / the counts to see what happened.

Required API key scopes

task:write

Request parameters

state
dismissal_reason
dismissal_note
string
snooze_for
integer
ids
array

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "outcome": "string",
      "status": "string",
      "detail": "string"
    }
  ],
  "transitioned_count": 0,
  "skipped_count": 0,
  "failed_count": 0,
  "not_found_count": 0
}

List all signals scout config

List the per-(team, skill) scout configs for this project — schedule (run_interval_minutes), enabled, and emit posture per scout. A freshly authored scout skill appears here once its config is registered, either explicitly via create or by the coordinator's next tick.

Required API key scopes

signal_scout:read

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

Example response

Status 200 Per-scout configs for this project, ordered by skill name.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "skill_name": "string",
  "description": "string",
  "scout_origin": "canonical",
  "enabled": true,
  "emit": true,
  "run_interval_minutes": 10,
  "last_run_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Create signals scout config

Register the config for a signals-scout-* skill immediately, without waiting for the coordinator to auto-register it — optionally setting run_interval_minutes, enabled, and emit in the same call. The skill must already exist on this project. Upsert: if a config already exists for the skill, the provided fields are applied to it.

Required API key scopes

signal_scout:write

Request parameters

skill_name
string
enabled
boolean
emit
boolean
run_interval_minutes
integer

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

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",
  "scout_origin": "canonical",
  "enabled": true,
  "emit": true,
  "run_interval_minutes": 10,
  "last_run_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 201 Created config.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "skill_name": "string",
  "description": "string",
  "scout_origin": "canonical",
  "enabled": true,
  "emit": true,
  "run_interval_minutes": 10,
  "last_run_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 No such skill on this project, the name lacks the `signals-scout-` prefix, or the project is already at its enabled-scouts maximum.

Update signals scout config

Tune one scout: change its schedule (run_interval_minutes), enabled, or emit (dry-run) posture. 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

enabled
boolean
emit
boolean
run_interval_minutes
integer

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 skill_name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/signals/scout/configs/{signal_id}/".format(
        project_id=project_id,
		signal_id="<the signal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"skill_name": "string"
	}
).json()

Example response

Status 200 Updated config.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "skill_name": "string",
  "description": "string",
  "scout_origin": "canonical",
  "enabled": true,
  "emit": true,
  "run_interval_minutes": 10,
  "last_run_at": "2019-08-24T14:15:22Z",
  "created_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.

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, and return all scout configs. Normally the Temporal coordinator does this on its next tick; this action exists so setup flows (e.g. the wizard's self-driving program) can hand the user a tunable fleet immediately.

Required API key scopes

signal_scout:write

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

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",
  "scout_origin": "canonical",
  "enabled": true,
  "emit": true,
  "run_interval_minutes": 10,
  "last_run_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve signals scout metadata

Return the project's scout metadata: whether it is enrolled, the current announcement banner (e.g. an alpha run-limit notice, or null when unset), and the enforced run limits with current usage. Limits reflect what the coordinator actually applies at dispatch, so a user can see the real throttle rather than what they assume they set. All values come from the signals-scout flag payload, so the banner and caps can change with no deploy.

Required API key scopes

signal_scout:read

Response

Example request

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

Example response

Status 200 This project's scout enrollment, announcement banner, and enforced run limits.

RESPONSE
{
  "enrolled": true,
  "banner_message": "string",
  "limits": {
    "max_runs_per_tick": 0,
    "max_runs_per_day": 0,
    "runs_today": 0,
    "runs_remaining_today": 0
  }
}

Retrieve signals scout project profile

Return the team's deterministic project profile. For the internal scout token the response reflects the newest non-expired cached row or a freshly-built one (lazy compute on cache miss); force_refresh=true skips the cache and rebuilds from authoritative sources. Public read callers (session auth or a signal_scout:read PAK) get the newest cached profile, or 404 if none has been built yet — they never trigger a rebuild. Read this at the start of a run to orient on the team's product mix, integrations, warehouse sources, signal coverage, and existing inbox surface.

Required API key scopes

signal_scout:read

Query parameters

force_refresh
boolean
Default: false

Response

Example request

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

Example response

Status 200 The team's current project profile (cached, or freshly built for the internal scout token).

RESPONSE
{
  "profile_id": "string",
  "computed_at": "string",
  "expires_at": "string",
  "source_version": "string",
  "payload": {
    "inventory": {
      "project_context": {
        "product_description": "string",
        "app_urls": [
          "string"
        ]
      },
      "products_in_use": [
        "string"
      ],
      "product_intents": [
        {
          "product_type": "string",
          "activated_at": "string",
          "created_at": "string"
        }
      ],
      "integrations": [
        {
          "kind": "string",
          "created_at": "string"
        }
      ],
      "external_data_sources": [
        {
          "source_type": "string",
          "status": "string",
          "prefix": "string",
          "created_at": "string"
        }
      ],
      "signal_source_configs": {
        "enabled": [
          {
            "source_product": "string",
            "source_type": "string"
          }
        ],
        "disabled": [
          {
            "source_product": "string",
            "source_type": "string"
          }
        ]
      },
      "existing_inbox_reports": {
        "total": 0,
        "by_status": [
          {
            "status": "string",
            "count": 0
          }
        ]
      },
      "recent_activity": {
        "window_days": 0,
        "by_scope": [
          {
            "scope": "string",
            "edits": 0,
            "users": 0,
            "last_edit": "string"
          }
        ]
      },
      "recent_dashboards": [
        {
          "id": 0,
          "name": "string",
          "last_accessed_at": "string",
          "last_refresh": "string",
          "created_at": "string"
        }
      ],
      "recent_surveys": {
        "total_count": 0,
        "active_count": 0,
        "recent": [
          {
            "id": "string",
            "name": "string",
            "type": "string",
            "status": "string",
            "updated_at": "string"
          }
        ]
      },
      "recent_feature_flags": {
        "total_count": 0,
        "active_count": 0,
        "recent": [
          {
            "id": 0,
            "key": "string",
            "name": "string",
            "active": true,
            "updated_at": "string"
          }
        ]
      },
      "recent_experiments": {
        "total_count": 0,
        "running_count": 0,
        "recent": [
          {
            "id": 0,
            "name": "string",
            "status": "string",
            "feature_flag_key": "string",
            "updated_at": "string"
          }
        ]
      },
      "recent_alerts": {
        "total_count": 0,
        "enabled_count": 0,
        "recent": [
          {
            "id": "string",
            "name": "string",
            "enabled": true,
            "state": "string",
            "calculation_interval": "string",
            "insight_id": 0,
            "created_at": "string"
          }
        ]
      },
      "recent_hog_functions": {
        "total_count": 0,
        "enabled_count": 0,
        "recent": [
          {
            "id": "string",
            "name": "string",
            "type": "string",
            "kind": "string",
            "enabled": true,
            "updated_at": "string"
          }
        ]
      },
      "recent_hog_flows": {
        "total_count": 0,
        "active_count": 0,
        "recent": [
          {
            "id": "string",
            "name": "string",
            "status": "string",
            "updated_at": "string"
          }
        ]
      },
      "recent_notebooks": {
        "total_count": 0,
        "recent": [
          {
            "short_id": "string",
            "title": "string",
            "last_modified_at": "string"
          }
        ]
      },
      "recent_cohorts": {
        "total_count": 0,
        "recent": [
          {
            "id": 0,
            "name": "string",
            "is_static": true,
            "count": 0,
            "created_at": "string"
          }
        ]
      },
      "recent_actions": {
        "total_count": 0,
        "recent": [
          {
            "id": 0,
            "name": "string",
            "updated_at": "string"
          }
        ]
      },
      "top_events": [
        {
          "event": "string",
          "count": 0,
          "distinct_users": 0,
          "recent_24h_count": 0,
          "recent_24h_users": 0,
          "first_seen": "string",
          "last_seen": "string"
        }
      ]
    }
  }
}

Status 404 No profile has been built for this team yet, and the caller is not the internal scout token (which builds on cache miss). Public read callers never trigger a build.

List all signals scout runs

Return the most recent SignalScoutRun summaries for this project, newest first. Used by the headless scout to dedupe against work other runs already covered. ILIKE matches on summary. date_from / date_to are a half-open window on created_at (>= date_from, < date_to); pass date_to on subsequent calls to walk past the 100-row cap. Pass emitted=true to see only runs that surfaced at least one finding. Pass skill_name (optionally with skill_version) to scope to a single scout. Results capped at 100.

Required API key scopes

signal_scout:read

Query parameters

date_from
string
date_to
string
emitted
booleannull
limit
integer
skill_name
string
skill_version
integer
text
string

Example request

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

Example response

Status 200 Recent run summaries newest-first.

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