signals

Search recent agent 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.

get/api/projects/{project_id}/signals/scout/runs/

Request

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

Path parameters

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/.

Query parameters

date_fromstring date-time

ISO-8601 inclusive lower bound on created_at. Omit to skip the lower bound.

date_tostring date-time

ISO-8601 exclusive upper bound on created_at. Pass to walk back past the result cap on subsequent calls (cursor-style: set to the created_at of the oldest run from the prior page).

emittedboolean nullable

Filter by emit outcome. true returns only runs that emitted at least one finding (emitted_count > 0); false returns only runs that emitted nothing. Omit for both.

limitinteger

Max rows to return (default 20, hard cap 100).

skill_namestring

Exact-match filter on the scout skill (e.g. signals-scout-errors). Narrows the run dump to a single scout — the primary scoping path when a specialist dedupes against its own past runs. Omit to span every scout on the team.

skill_versioninteger

Exact-match filter on the skill version. Pair with skill_name to pin one version; omit for all.

textstring

Case-insensitive substring match on the scout's end-of-run summary. Omit to skip the filter.

Response

Recent run summaries newest-first.

run_idstring required

UUID of the bridge row.

skill_namestring required

Canonical skill name the run executed (e.g. signals-scout-general).

skill_versioninteger required

Skill version snapshotted at run start.

status'not_started' | 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' required
  • not_started - not_started
  • queued - queued
  • in_progress - in_progress
  • completed - completed
  • failed - failed
  • cancelled - cancelled
created_atstring required

ISO-8601 timestamp the bridge row was created — the field date_from / date_to filter and order on. Use this (not started_at) as the date_to cursor when walking past the 100-row cap, so runs created in the gap between a boundary run's TaskRun and its bridge row aren't skipped.

started_atstring required

ISO-8601 timestamp the TaskRun was created.

completed_atstring nullable required

ISO-8601 timestamp the TaskRun completed; null while still running.

task_idstring nullable

UUID of the Tasks Task the scout span ran inside.

task_run_idstring nullable

UUID of the Tasks TaskRun. Pairs with task_id to deep-link.

task_urlstring nullable

Relative deep-link to the Tasks UI for this run, e.g. /project/{team_id}/tasks/{task_id}?runId={task_run_id}.

summarystring required

One-paragraph close-out the scout wrote at end-of-run. Empty string for runs that errored before close-out. The dedupe key for non-emitting runs.

errorstring nullable

Full error_message from the linked TaskRun, surfaced only for failed/cancelled runs (null otherwise, including on success). Use failure_reason for a concise scan-friendly summary.

failure_reasonstring nullable

Concise derived reason the run didn't complete cleanly — the first line of error (bounded), or a status-derived fallback. Null unless the run terminated failed/cancelled. Read this to see at a glance why a run emitted nothing without pulling full stack traces.

emitted_countinteger required

Number of findings this run actually emitted to the inbox. 0 for runs that investigated but surfaced nothing, or ran dry-run / before AI approval. > 0 means the run produced at least one Signal.

emitted_finding_idsstring[] required

The finding_ids behind emitted_count, in emit order. Each maps to a Signal with source_id = run:<run_id>:finding:<finding_id>. Empty for non-emitting runs.

emitted_report_idsstring[] required

The SignalReport ids this run authored directly via the emit_report channel, in emit order. Separate from emitted_finding_ids (weak emit_signal findings) — a report-authoring scout writes a full report here instead. Empty for runs that authored no report.

edited_report_idsstring[] required

The SignalReport ids this run mutated via the edit_report channel (rewrote title/summary and/or appended a note), deduped. Distinct from emitted_report_ids: edit can target any inbox report, so these are generally not reports the run authored. Empty for runs that edited no report.

Changes

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