Signals API Reference

Signals

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

Endpoints

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

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
include_all_statuses
boolean
limit
integer
offset
integer
ordering
string
priority
string
scout
string
search
string
source_id
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"
      ],
      "scout_name": "string",
      "implementation_pr_url": "string",
      "implementation_pr_merged": true,
      "refund": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "reason": "pr_incorrect",
        "note": "string",
        "billing_path": "excluded",
        "credits": 0,
        "pr_url": "string",
        "pr_run_created_at": "2019-08-24T14:15:22Z",
        "credit_amount_usd": "string",
        "billing_synced": true,
        "created_at": "2019-08-24T14:15:22Z"
      },
      "refund_ineligibility_reason": "already_refunded",
      "billing_exempt_reason": "posthog_health_check"
    }
  ]
}

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"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "implementation_pr_merged": true,
  "refund": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "reason": "pr_incorrect",
    "note": "string",
    "billing_path": "excluded",
    "credits": 0,
    "pr_url": "string",
    "pr_run_created_at": "2019-08-24T14:15:22Z",
    "credit_amount_usd": "string",
    "billing_synced": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "refund_ineligibility_reason": "already_refunded",
  "billing_exempt_reason": "posthog_health_check"
}

Update signals reports

Edit the human-facing title and/or summary (description) of a signal report, addressed by id. Both fields are optional — supply only the ones you want to change; at least one is required. Every other report field (status, weights, judgments) is managed by the signals pipeline and cannot be set here. Returns the full updated report.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

title
string
summary
string

Response

Example request

PATCH /api/projects/:project_id/signals/reports/: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/:id/\
	-d title="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<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)},
	data={
		"title": "string"
	}
).json()

Example response

Status 200 Report updated.

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"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "implementation_pr_merged": true,
  "refund": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "reason": "pr_incorrect",
    "note": "string",
    "billing_path": "excluded",
    "credits": 0,
    "pr_url": "string",
    "pr_run_created_at": "2019-08-24T14:15:22Z",
    "credit_amount_usd": "string",
    "billing_synced": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "refund_ineligibility_reason": "already_refunded",
  "billing_exempt_reason": "posthog_health_check"
}

Status 400 Neither title nor summary supplied, or a value failed validation.

Status 404 Report not found for this project.

Retrieve signals report pr

Fetch the CI status (GitHub Actions check runs and legacy commit statuses) of the pull request the report's implementation task opened, via the team's GitHub integration.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/signals/reports/:id/pr_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/reports/:id/pr_checks/
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}/pr_checks/".format(
        project_id=project_id,
		signal_id="<the signal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 The CI checks on the report's implementation pull request.

RESPONSE
{
  "checks": [
    {
      "name": "string",
      "status": "string",
      "conclusion": "string",
      "url": "string"
    }
  ]
}

Status 404 Report has no implementation PR, or no GitHub integration can access it.

Status 502 GitHub could not return the checks.

Status 503 The GitHub egress budget is temporarily unavailable.

Retrieve signals report pr

Fetch the pull request's conversation comments and inline review comments, merged chronologically, via the team's GitHub integration.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/signals/reports/:id/pr_comments
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/pr_comments/
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}/pr_comments/".format(
        project_id=project_id,
		signal_id="<the signal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Conversation and review comments on the report's implementation pull request.

RESPONSE
{
  "comments": [
    {
      "id": "string",
      "author": "string",
      "author_avatar_url": "string",
      "body": "string",
      "created_at": "string",
      "url": "string",
      "comment_type": "conversation",
      "path": "string",
      "line": 0,
      "start_line": 0,
      "side": "LEFT",
      "diff_hunk": "string",
      "in_reply_to_id": "string",
      "commit_id": "string"
    }
  ]
}

Status 404 Report has no implementation PR, or no GitHub integration can access it.

Status 502 GitHub could not return the comments.

Status 503 The GitHub egress budget is temporarily unavailable.

Create signals reports refund

Refund the flat charge for this report's implementation PR and archive the report. Refunds auto-approve: the charge is either excluded from usage before it is ever reported to billing (refund on the same UTC day as the PR run) or returned as a Stripe customer-balance credit on the next invoice. A refunded PR does not count toward the free monthly PR allowance. One refund per report, ever — repeat calls return the existing refund with already_refunded=true. The report is archived as part of the refund (a resolved report stays resolved) and can't be restored afterwards.

Required API key scopes

task:write

Path parameters

id
string

Request parameters

reason
note
string

Response

Example request

POST /api/projects/:project_id/signals/reports/:id/refund
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/refund/\
	-d reason=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}/refund/".format(
        project_id=project_id,
		signal_id="<the signal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200 The refund (created, or the existing one with already_refunded=true when the report was refunded before).

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "reason": "pr_incorrect",
  "note": "string",
  "billing_path": "excluded",
  "credits": 0,
  "pr_url": "string",
  "pr_run_created_at": "2019-08-24T14:15:22Z",
  "credit_amount_usd": "string",
  "billing_synced": true,
  "created_at": "2019-08-24T14:15:22Z",
  "already_refunded": false
}

Status 400 Report is not refundable: no billable implementation PR, the PR run is outside the current billing period, or the report is system-marked never-billable.

Status 404 Report not found, or refunds are not enabled for this organization.

Retrieve signals reports signals

Fetch all signals for a report from ClickHouse, including full metadata.

Required API key scopes

task:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/signals/reports/:id/signals
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/signals/
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}/signals/".format(
        project_id=project_id,
		signal_id="<the signal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "report": {
    "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"
    ],
    "scout_name": "string",
    "implementation_pr_url": "string",
    "implementation_pr_merged": true,
    "refund": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "reason": "pr_incorrect",
      "note": "string",
      "billing_path": "excluded",
      "credits": 0,
      "pr_url": "string",
      "pr_run_created_at": "2019-08-24T14:15:22Z",
      "credit_amount_usd": "string",
      "billing_synced": true,
      "created_at": "2019-08-24T14:15:22Z"
    },
    "refund_ineligibility_reason": "already_refunded",
    "billing_exempt_reason": "posthog_health_check"
  },
  "signals": [
    {
      "signal_id": "string",
      "content": "string",
      "source_product": "session_replay",
      "source_type": "session_analysis_cluster",
      "source_id": "string",
      "weight": 0.1,
      "timestamp": "2019-08-24T14:15:22Z",
      "extra": {
        "session_id": "string",
        "segment_title": "string",
        "start_time": "string",
        "end_time": "string",
        "problem_type": "confusion",
        "distinct_id": "string",
        "session_start_time": null,
        "session_end_time": null,
        "session_duration": null,
        "session_active_seconds": null,
        "exported_asset_id": null,
        "event_history": null
      },
      "match_metadata": {
        "parent_signal_id": "string",
        "match_query": "string",
        "reason": "string",
        "specificity": {
          "pr_title": "string",
          "specific_enough": true,
          "reason": "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" | "resolved", # Optional dismissal feedback (honored when state == "suppressed", "potential", or "resolved"): "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"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "implementation_pr_merged": true,
  "refund": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "reason": "pr_incorrect",
    "note": "string",
    "billing_path": "excluded",
    "credits": 0,
    "pr_url": "string",
    "pr_run_created_at": "2019-08-24T14:15:22Z",
    "credit_amount_usd": "string",
    "billing_synced": true,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "refund_ineligibility_reason": "already_refunded",
  "billing_exempt_reason": "posthog_health_check"
}

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
}

Retrieve signals reports refund summary

Aggregate credited-path refunds across the whole organization for the current billing period — counts only, no per-team detail. The billing usage widget needs this because billing usage is org-wide while reports (and their refunds) are team-scoped: subtract the refunded credits from billing usage to show the net PR count. Excluded-path refunds never reach billing usage, so no adjustment is needed for them. Also carries the org's live billable credits for the period (billing's recorded usage lags by up to a day), so the widget can count just-created PRs and react to same-day refunds.

Required API key scopes

task:read

Response

Example request

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

Example response

Status 200 Org-wide credited-refund totals for the current billing period.

RESPONSE
{
  "credited_refund_count": 0,
  "credited_credits": 0,
  "period_billable_credits": 0
}

Status 404 Refunds are not enabled for this organization.

Create signals scout

Create a signals-scout-* skill and its runnable config atomically. The skill always receives the report-channel tools. The optional config controls schedule, enablement, dry-run posture, and typed destinations such as Slack. Repeating the same definition is safe and applies any supplied config fields; reusing its name for a different definition returns 409.

Required API key scopes

llm_skill:writesignal_scout:write

Request parameters

name
string
description
string
body
string
files
array
config

Response

Example request

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

Example response

Status 200 The scout definition already existed; the requested config fields were applied.

RESPONSE
{
  "created": true,
  "skill": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "version": 0,
    "allowed_tools": [
      "string"
    ]
  },
  "config": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "skill_name": "string",
    "description": "string",
    "scout_origin": "canonical",
    "enabled": true,
    "emit": true,
    "run_interval_minutes": 30,
    "run_cron_schedule": "string",
    "output_destinations": {
      "slack": {
        "integration_id": 1,
        "channel": "string"
      }
    },
    "last_run_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  }
}

Status 201 The scout skill, config, or both were created.

RESPONSE
{
  "created": true,
  "skill": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "description": "string",
    "version": 0,
    "allowed_tools": [
      "string"
    ]
  },
  "config": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "skill_name": "string",
    "description": "string",
    "scout_origin": "canonical",
    "enabled": true,
    "emit": true,
    "run_interval_minutes": 30,
    "run_cron_schedule": "string",
    "output_destinations": {
      "slack": {
        "integration_id": 1,
        "channel": "string"
      }
    },
    "last_run_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  }
}