signals

Run a scout now

Dispatch one on-demand run of this scout immediately, regardless of its schedule. Useful to test a scout right after authoring it, or to refresh its findings on demand. The run executes asynchronously on the worker and inherits every guard the scheduled path has: it is forbidden if scouts are not enabled for the project (403), and skipped if self-driving is paused at the project's pull request limit, or the project is over its daily report limit or daily run budget (429), or a run for this scout is already in progress (409). A manual run counts against the same daily run budget as scheduled runs, so repeated manual runs of the same scout can exhaust the project's daily allowance. A manual run does not change the scout's schedule or last_run_at. A disabled scout can still be run this way (to test before enabling). Pass an optional note to steer this one run without leaving a scout note that would steer every later run too. Returns immediately with the workflow id: poll the scout's runs for the result.

post/api/projects/{project_id}/signals/scout/configs/{id}/run/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/signals/scout/configs/{id}/run/
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

idstring uuid required

A UUID string identifying this Signal scout config.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

notestring

Optional steering for this run only, such as 'focus on the checkout regression' or 'skip the staging traffic today'. The agent reads it alongside the scout's durable notes and weighs it the same way: it directs attention, it never forces a finding. Use it instead of leaving a scout note that would also steer every later scheduled run. The note is kept on the run for history and is never read by another run. Because the agent reads it verbatim while holding privileged tools, a run that carries one needs llm_skill:write on top of signal_scout:write, plus editor access to skills, the same bar as leaving a note.

Response

A run was dispatched. It executes asynchronously; poll the scout's runs for the result.

skill_namestring required

The signals-scout-* skill that was dispatched.

workflow_idstring required

Temporal workflow id for the dispatched run. The run executes asynchronously; poll the scout's runs to see the resulting run row, its status, and any emitted findings.

startedboolean required

True when a new run was dispatched. The endpoint returns 409 instead when a run for this scout is already in progress.

Changes

No recorded changes to this operation across all 1 revision of this API.