Signals

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

Endpoints

GET
POST
GET
DELETE
GET
GET
PATCH
DELETE
POST
POST
POST
GET
GET
POST
PATCH
DELETE
POST
DELETE
POST
Next page →

List all signals config

Team-level signal autonomy config (singleton per team).

GET /signals/config/ → retrieve POST /signals/config/ → update

Required API key scopes

task:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "autostart_enabled": true,
  "default_autostart_priority": "P0",
  "default_slack_notification_channel": "string",
  "autostart_base_branches": {
    "property1": "string",
    "property2": "string"
  },
  "issue_tracking_integration": 0,
  "issue_tracking_config": {
    "property1": "string",
    "property2": "string"
  },
  "max_reports_per_day": 1,
  "default_open_pull_request_ready": true,
  "github_issue_writeback_enabled": true,
  "pull_request_label_enabled": true,
  "pull_request_label": "string",
  "reports_generated_today": 0,
  "daily_report_limit_reached": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create signals config

Partial update of the per-project singleton. Omitted fields keep their value.

Required API key scopes

task:write

Request parameters

  • autostart_enabled
    boolean | null
  • default_autostart_priority
  • default_slack_notification_channel
    string | null
  • autostart_base_branches
    object
  • issue_tracking_integration
    integer | null
  • issue_tracking_config
    object
  • max_reports_per_day
    integer | null
  • default_open_pull_request_ready
    boolean
  • github_issue_writeback_enabled
    boolean
  • pull_request_label_enabled
    boolean
  • pull_request_label
    string | null

Response


Example request

POST /api/projects/:project_id/signals/config
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/config/\
	-d autostart_enabled="boolean"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "autostart_enabled": true,
  "default_autostart_priority": "P0",
  "default_slack_notification_channel": "string",
  "autostart_base_branches": {
    "property1": "string",
    "property2": "string"
  },
  "issue_tracking_integration": 0,
  "issue_tracking_config": {
    "property1": "string",
    "property2": "string"
  },
  "max_reports_per_day": 1,
  "default_open_pull_request_ready": true,
  "github_issue_writeback_enabled": true,
  "pull_request_label_enabled": true,
  "pull_request_label": "string",
  "reports_generated_today": 0,
  "daily_report_limit_reached": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

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/

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/

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

  • actionability
    string
  • already_addressed
    boolean
  • assignee
    string
    One of: "me"
  • channel_id
    string
  • count_only
    boolean
    Default: false
  • created_after
    string
  • has_implementation_pr
    boolean
  • include_all_statuses
    boolean
  • include_source_metadata
    boolean
    Default: true
  • limit
    integer
  • offset
    integer
  • ordering
    string
  • priority
    string
  • scope
    string
  • scout
    string
  • scout_prefix
    string
  • search
    string
  • sort
    string
  • source_id
    string
  • source_product
    string
  • status
    string
  • suggested_reviewers
    string
  • task_id
    string
  • teammate_uuid
    string
  • unclaimed
    boolean
  • unread
    boolean
  • use_priority_preference
    boolean
  • view
    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/

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",
      "summary_lead": "string",
      "status": "potential",
      "total_weight": 0.1,
      "signal_count": 0,
      "signals_at_run": 0,
      "collapsed_note_count": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "artefact_count": 0,
      "charts": [
        {
          "chart_id": "string",
          "title": "string",
          "query": null,
          "caption": "string",
          "size": "small"
        }
      ],
      "metrics": [
        {
          "metric_id": "string",
          "title": "string",
          "kind": "affected_users",
          "role": "supporting",
          "value": 0,
          "value_at": "2019-08-24T14:15:22Z",
          "series": [
            0.1
          ],
          "value_format": "number",
          "unit": "string",
          "caption": "string",
          "goal_value": 0,
          "goal_direction": "at_most",
          "goal_grain": "whole_window",
          "decision_window_days": 1,
          "minimum_data_points": 1
        }
      ],
      "suggested_prompts": [
        "string"
      ],
      "priority": "string",
      "actionability": "string",
      "already_addressed": true,
      "dismissal_reason": "string",
      "dismissal_note": "string",
      "repo_slug": "string",
      "is_suggested_reviewer": false,
      "source_products": [
        "string"
      ],
      "scout_name": "string",
      "implementation_pr_url": "string",
      "pull_requests": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "url": "http://example.com",
          "state": "unknown",
          "merged": true,
          "review_decision": "approved",
          "merged_at": "2019-08-24T14:15:22Z",
          "attached_by": {
            "kind": "user",
            "user": {
              "id": 0,
              "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
              "first_name": "string",
              "last_name": "string",
              "email": "user@example.com"
            },
            "agent": "string",
            "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
          },
          "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
          "attached_at": "2019-08-24T14:15:22Z"
        }
      ],
      "implementation_pr_state": "unknown",
      "implementation_pr_merged": true,
      "tracker_issue_url": "string",
      "tracker_issue_reference": "string",
      "tracker_issue_error": "string",
      "work_state": "unclaimed",
      "assignee": {
        "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
        "kind": "user",
        "user": {
          "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",
        "agent": "string",
        "claimed_at": "2019-08-24T14:15:22Z"
      },
      "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",
      "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
      "ranking": {
        "served_key": "string",
        "model_name": "string",
        "model_version": "string",
        "manifest_version": "string",
        "scored_at": "2019-08-24T14:15:22Z",
        "scores": {
          "property1": 0.1,
          "property2": 0.1
        },
        "lifts": {
          "property1": 0.1,
          "property2": 0.1
        },
        "readable_heads": [
          "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/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "summary": "string",
  "summary_lead": "string",
  "status": "potential",
  "total_weight": 0.1,
  "signal_count": 0,
  "signals_at_run": 0,
  "collapsed_note_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "artefact_count": 0,
  "charts": [
    {
      "chart_id": "string",
      "title": "string",
      "query": null,
      "caption": "string",
      "size": "small"
    }
  ],
  "metrics": [
    {
      "metric_id": "string",
      "title": "string",
      "kind": "affected_users",
      "role": "supporting",
      "value": 0,
      "value_at": "2019-08-24T14:15:22Z",
      "series": [
        0.1
      ],
      "value_format": "number",
      "unit": "string",
      "query": null,
      "caption": "string",
      "goal_value": 0,
      "goal_direction": "at_most",
      "goal_grain": "whole_window",
      "decision_window_days": 1,
      "minimum_data_points": 1
    }
  ],
  "suggested_prompts": [
    "string"
  ],
  "priority": "string",
  "actionability": "string",
  "already_addressed": true,
  "dismissal_reason": "string",
  "dismissal_note": "string",
  "repo_slug": "string",
  "is_suggested_reviewer": false,
  "source_products": [
    "string"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "pull_requests": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "http://example.com",
      "state": "unknown",
      "merged": true,
      "review_decision": "approved",
      "merged_at": "2019-08-24T14:15:22Z",
      "attached_by": {
        "kind": "user",
        "user": {
          "id": 0,
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "first_name": "string",
          "last_name": "string",
          "email": "user@example.com"
        },
        "agent": "string",
        "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
      },
      "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
      "attached_at": "2019-08-24T14:15:22Z"
    }
  ],
  "implementation_pr_state": "unknown",
  "implementation_pr_merged": true,
  "tracker_issue_url": "string",
  "tracker_issue_reference": "string",
  "tracker_issue_error": "string",
  "work_state": "unclaimed",
  "assignee": {
    "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
    "kind": "user",
    "user": {
      "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",
    "agent": "string",
    "claimed_at": "2019-08-24T14:15:22Z"
  },
  "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",
  "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  "ranking": {
    "served_key": "string",
    "model_name": "string",
    "model_version": "string",
    "manifest_version": "string",
    "scored_at": "2019-08-24T14:15:22Z",
    "scores": {
      "property1": 0.1,
      "property2": 0.1
    },
    "lifts": {
      "property1": 0.1,
      "property2": 0.1
    },
    "readable_heads": [
      "string"
    ]
  }
}

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"

Example response

Status 200 Report updated.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "summary": "string",
  "summary_lead": "string",
  "status": "potential",
  "total_weight": 0.1,
  "signal_count": 0,
  "signals_at_run": 0,
  "collapsed_note_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "artefact_count": 0,
  "charts": [
    {
      "chart_id": "string",
      "title": "string",
      "query": null,
      "caption": "string",
      "size": "small"
    }
  ],
  "metrics": [
    {
      "metric_id": "string",
      "title": "string",
      "kind": "affected_users",
      "role": "supporting",
      "value": 0,
      "value_at": "2019-08-24T14:15:22Z",
      "series": [
        0.1
      ],
      "value_format": "number",
      "unit": "string",
      "query": null,
      "caption": "string",
      "goal_value": 0,
      "goal_direction": "at_most",
      "goal_grain": "whole_window",
      "decision_window_days": 1,
      "minimum_data_points": 1
    }
  ],
  "suggested_prompts": [
    "string"
  ],
  "priority": "string",
  "actionability": "string",
  "already_addressed": true,
  "dismissal_reason": "string",
  "dismissal_note": "string",
  "repo_slug": "string",
  "is_suggested_reviewer": false,
  "source_products": [
    "string"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "pull_requests": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "http://example.com",
      "state": "unknown",
      "merged": true,
      "review_decision": "approved",
      "merged_at": "2019-08-24T14:15:22Z",
      "attached_by": {
        "kind": "user",
        "user": {
          "id": 0,
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "first_name": "string",
          "last_name": "string",
          "email": "user@example.com"
        },
        "agent": "string",
        "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
      },
      "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
      "attached_at": "2019-08-24T14:15:22Z"
    }
  ],
  "implementation_pr_state": "unknown",
  "implementation_pr_merged": true,
  "tracker_issue_url": "string",
  "tracker_issue_reference": "string",
  "tracker_issue_error": "string",
  "work_state": "unclaimed",
  "assignee": {
    "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
    "kind": "user",
    "user": {
      "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",
    "agent": "string",
    "claimed_at": "2019-08-24T14:15:22Z"
  },
  "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",
  "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  "ranking": {
    "served_key": "string",
    "model_name": "string",
    "model_version": "string",
    "manifest_version": "string",
    "scored_at": "2019-08-24T14:15:22Z",
    "scores": {
      "property1": 0.1,
      "property2": 0.1
    },
    "lifts": {
      "property1": 0.1,
      "property2": 0.1
    },
    "readable_heads": [
      "string"
    ]
  }
}
Status 400 Neither title nor summary supplied, or a value failed validation.
Status 404 Report not found for this project.

Delete signals reports

Soft-delete a report and its signals via the deletion workflow.

Required API key scopes

task:write

Path parameters

  • id
    string

Response


Example request

DELETE /api/projects/:project_id/signals/reports/: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/:id/

Example response

Status 200 A deletion is already running.
RESPONSE
{
  "status": "deletion_started",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971"
}
Status 202 Deletion started.
RESPONSE
{
  "status": "deletion_started",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971"
}

Create signals reports

Start or update work for the current user, internal task, or external agent. Supply claim_id to resume, pull_requests to add PRs, takeover=true to explicitly take ownership, or release=true to end ownership while preserving work history and PR links.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • claim_id
    string
  • pull_requests
    array
  • takeover
    boolean
    Default: false
  • pr_url
    string
  • release
    boolean
    Default: false

Response


Example request

POST /api/projects/:project_id/signals/reports/:id/claim
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/claim/\
	-d claim_id="string"

Example response

Status 200 Current report and assignment.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "title": "string",
  "summary": "string",
  "summary_lead": "string",
  "status": "potential",
  "total_weight": 0.1,
  "signal_count": 0,
  "signals_at_run": 0,
  "collapsed_note_count": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "artefact_count": 0,
  "charts": [
    {
      "chart_id": "string",
      "title": "string",
      "query": null,
      "caption": "string",
      "size": "small"
    }
  ],
  "metrics": [
    {
      "metric_id": "string",
      "title": "string",
      "kind": "affected_users",
      "role": "supporting",
      "value": 0,
      "value_at": "2019-08-24T14:15:22Z",
      "series": [
        0.1
      ],
      "value_format": "number",
      "unit": "string",
      "query": null,
      "caption": "string",
      "goal_value": 0,
      "goal_direction": "at_most",
      "goal_grain": "whole_window",
      "decision_window_days": 1,
      "minimum_data_points": 1
    }
  ],
  "suggested_prompts": [
    "string"
  ],
  "priority": "string",
  "actionability": "string",
  "already_addressed": true,
  "dismissal_reason": "string",
  "dismissal_note": "string",
  "repo_slug": "string",
  "is_suggested_reviewer": false,
  "source_products": [
    "string"
  ],
  "scout_name": "string",
  "implementation_pr_url": "string",
  "pull_requests": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "url": "http://example.com",
      "state": "unknown",
      "merged": true,
      "review_decision": "approved",
      "merged_at": "2019-08-24T14:15:22Z",
      "attached_by": {
        "kind": "user",
        "user": {
          "id": 0,
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "first_name": "string",
          "last_name": "string",
          "email": "user@example.com"
        },
        "agent": "string",
        "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
      },
      "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
      "attached_at": "2019-08-24T14:15:22Z"
    }
  ],
  "implementation_pr_state": "unknown",
  "implementation_pr_merged": true,
  "tracker_issue_url": "string",
  "tracker_issue_reference": "string",
  "tracker_issue_error": "string",
  "work_state": "unclaimed",
  "assignee": {
    "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
    "kind": "user",
    "user": {
      "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",
    "agent": "string",
    "claimed_at": "2019-08-24T14:15:22Z"
  },
  "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",
  "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
  "ranking": {
    "served_key": "string",
    "model_name": "string",
    "model_version": "string",
    "manifest_version": "string",
    "scored_at": "2019-08-24T14:15:22Z",
    "scores": {
      "property1": 0.1,
      "property2": 0.1
    },
    "lifts": {
      "property1": 0.1,
      "property2": 0.1
    },
    "readable_heads": [
      "string"
    ]
  }
}
Status 400 The pull request URL or request shape is invalid.
Status 409 The report cannot be claimed or released in its current state.

Create signals reports feedback

Record the thumbs rating at the end of a report, with an optional note. For browser-session requests the rating is persisted as a per-person report action, which counts as consumption evidence for the scout that authored the report (scouts whose output nobody consumes are eventually paused); requests authenticated any other way record no action. When a note is present and the report was authored by a scout, the note is also forwarded to that scout as a steering note it reads on its next run; for any other report there is nothing to steer. The report's state is never changed.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • sentiment
  • note
    string
    Default:

Response


Example request

POST /api/projects/:project_id/signals/reports/:id/feedback
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/feedback/\
	-d sentiment=undefined

Example response

Status 200
RESPONSE
{
  "forwarded": true
}

Create signals reports merge

Fold one or more duplicate reports into this report, which survives. The sources' signals, work-log artefacts, pull requests, task runs and checks move onto the survivor, the survivor's signal counters take on theirs, and each source is archived with a 'duplicate of' link back to the survivor. A source's open pull request stays open, because the survivor holds it after the move. Pick the survivor deliberately: prefer the older report, and prefer the one with an open implementation PR or an active claim. Any active claim on a source is released, so re-claim the survivor if you were working on one. Titles and summaries are not combined, so edit it afterwards if it needs a rewrite. A merged report keeps its URL but cannot be restored, because its signals now belong to the survivor.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • source_report_ids
    array
  • reason
    string

Response


Example request

POST /api/projects/:project_id/signals/reports/:id/merge
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/merge/\
	-d source_report_ids="array"

Example response

Status 200 The surviving report after the merge, plus one result per merged source.
RESPONSE
{
  "report": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "title": "string",
    "summary": "string",
    "summary_lead": "string",
    "status": "potential",
    "total_weight": 0.1,
    "signal_count": 0,
    "signals_at_run": 0,
    "collapsed_note_count": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "artefact_count": 0,
    "charts": [
      {
        "chart_id": "string",
        "title": "string",
        "query": null,
        "caption": "string",
        "size": "small"
      }
    ],
    "metrics": [
      {
        "metric_id": "string",
        "title": "string",
        "kind": "affected_users",
        "role": "supporting",
        "value": 0,
        "value_at": "2019-08-24T14:15:22Z",
        "series": [
          0.1
        ],
        "value_format": "number",
        "unit": "string",
        "query": null,
        "caption": "string",
        "goal_value": 0,
        "goal_direction": "at_most",
        "goal_grain": "whole_window",
        "decision_window_days": 1,
        "minimum_data_points": 1
      }
    ],
    "suggested_prompts": [
      "string"
    ],
    "priority": "string",
    "actionability": "string",
    "already_addressed": true,
    "dismissal_reason": "string",
    "dismissal_note": "string",
    "repo_slug": "string",
    "is_suggested_reviewer": false,
    "source_products": [
      "string"
    ],
    "scout_name": "string",
    "implementation_pr_url": "string",
    "pull_requests": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "url": "http://example.com",
        "state": "unknown",
        "merged": true,
        "review_decision": "approved",
        "merged_at": "2019-08-24T14:15:22Z",
        "attached_by": {
          "kind": "user",
          "user": {
            "id": 0,
            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
            "first_name": "string",
            "last_name": "string",
            "email": "user@example.com"
          },
          "agent": "string",
          "task_id": "736fde4d-9029-4915-8189-01353d6982cb"
        },
        "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
        "attached_at": "2019-08-24T14:15:22Z"
      }
    ],
    "implementation_pr_state": "unknown",
    "implementation_pr_merged": true,
    "tracker_issue_url": "string",
    "tracker_issue_reference": "string",
    "tracker_issue_error": "string",
    "work_state": "unclaimed",
    "assignee": {
      "claim_id": "6ed32748-64af-4d95-94ea-a78b6397033c",
      "kind": "user",
      "user": {
        "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",
      "agent": "string",
      "claimed_at": "2019-08-24T14:15:22Z"
    },
    "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",
    "channel_id": "bbe8aa76-a4bb-46f6-a785-df8e831cc459",
    "ranking": {
      "served_key": "string",
      "model_name": "string",
      "model_version": "string",
      "manifest_version": "string",
      "scored_at": "2019-08-24T14:15:22Z",
      "scores": {
        "property1": 0.1,
        "property2": 0.1
      },
      "lifts": {
        "property1": 0.1,
        "property2": 0.1
      },
      "readable_heads": [
        "string"
      ]
    }
  },
  "sources": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "artefacts_moved": 0,
      "signals_moved": 0,
      "released_claim": true
    }
  ]
}
Status 404 The surviving report was not found in this project.
Status 409 Both ends of a merge must be a live report of this project. Returned when the survivor is resolved, or when a source is the survivor itself, is resolved or archived, is still being researched, carries more signals than one merge can move, or belongs to another project. Nothing is applied.

Retrieve signals report pr

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

Required API key scopes

task:read

Path parameters

  • id
    string

Query parameters

  • pull_request_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/

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 403 GitHub is connected without permission to read pull request checks.
RESPONSE
{
  "code": "string",
  "error": "string",
  "remediation_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

Query parameters

  • pull_request_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/

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",
      "reactions": [
        {
          "id": "string",
          "content": "string",
          "user_login": "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 report pr review comments

Post an inline review comment on the report's implementation pull request, attributed to the requesting user's own GitHub identity via their personal GitHub connection. Either replies to an existing thread (in_reply_to) or starts a new thread on a diff line (path + line).

Required API key scopes

task:write

Path parameters

  • id
    string

Query parameters

  • pull_request_id
    string

Request parameters

  • body
    string
  • in_reply_to
    string | null
  • path
    string | null
  • line
    integer | null
  • side

Response


Example request

POST /api/projects/:project_id/signals/reports/:id/pr_review_comments
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/pr_review_comments/\
	-d body="string"

Example response

Status 201 The created review comment, in the normalized PR-comment shape.
RESPONSE
{
  "comment": {
    "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",
    "reactions": [
      {
        "id": "string",
        "content": "string",
        "user_login": "string"
      }
    ]
  }
}
Status 400 Invalid comment payload.
Status 403 Not a signed-in user, or the requesting user has no usable personal GitHub connection (reconnect GitHub).
Status 404 Report has no implementation PR, or no GitHub integration can access it.
Status 502 GitHub rejected the comment.
Status 503 The GitHub egress budget is temporarily unavailable.

Update signals report pr review comment

Required API key scopes

task:write

Path parameters

  • comment_id
    string
  • id
    string

Query parameters

  • pull_request_id
    string

Request parameters

  • body
    string

Response


Example request

PATCH /api/projects/:project_id/signals/reports/:id/pr_review_comments/:comment_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/pr_review_comments/:comment_id/\
	-d body="string"

Example response

Status 200 The edited review comment, in the normalized PR-comment shape.
RESPONSE
{
  "comment": {
    "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",
    "reactions": [
      {
        "id": "string",
        "content": "string",
        "user_login": "string"
      }
    ]
  }
}
Status 403 Not a signed-in user, no usable personal GitHub connection, or not the comment's author.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the edit.
Status 503 The GitHub egress budget is temporarily unavailable.

Delete signals report pr review comment

Required API key scopes

task:write

Path parameters

  • comment_id
    string
  • id
    string

Query parameters

  • pull_request_id
    string

Example request

DELETE /api/projects/:project_id/signals/reports/:id/pr_review_comments/:comment_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/:id/pr_review_comments/:comment_id/

Example response

Status 204 Comment deleted.
Status 403 Not a signed-in user, no usable personal GitHub connection, or not the comment's author.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the delete.
Status 503 The GitHub egress budget is temporarily unavailable.

Create signals report pr review comment reactions

Required API key scopes

task:write

Path parameters

  • comment_id
    string
  • id
    string

Query parameters

  • pull_request_id
    string

Request parameters

  • content

Response


Example request

POST /api/projects/:project_id/signals/reports/:id/pr_review_comments/:comment_id/reactions
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/pr_review_comments/:comment_id/reactions/\
	-d content=undefined

Example response

Status 201 The created reaction.
RESPONSE
{
  "reaction": {
    "id": "string",
    "content": "string",
    "user_login": "string"
  }
}
Status 403 Not a signed-in user, or no usable personal GitHub connection.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the reaction.
Status 503 The GitHub egress budget is temporarily unavailable.

Delete signals report pr review comment reaction

Required API key scopes

task:write

Path parameters

  • comment_id
    string
  • id
    string
  • reaction_id
    string

Query parameters

  • pull_request_id
    string

Example request

DELETE /api/projects/:project_id/signals/reports/:id/pr_review_comments/:comment_id/reactions/:reaction_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/:id/pr_review_comments/:comment_id/reactions/:reaction_id/

Example response

Status 204 Reaction removed.
Status 403 Not a signed-in user, or no usable personal GitHub connection.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the removal.
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

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.
Next page →