action posthog_signals_scout_config_list {
  label: "List scout configs"
  description: "List the per-(team, skill) scout configs for this project. Each row includes its schedule (rolling `run_interval_minutes`, or a project-local `run_cron_schedule` when set), `enabled`, `emit` posture, and `tags`. A freshly authored scout skill appears here once its config is registered, either explicitly via create or by the coordinator's next tick. Pass `tags` to narrow the fleet to the scouts carrying at least one of the given labels."
  provider: posthog
  method: GET
  path: "/api/projects/{project_id}/signals/scout/configs/"
  encoding: json
  input: {
    type: "object"
    properties: {
      tags: {
        type: "string"
      }
    }
    additionalProperties: false
  }
  output: {
    type: "array"
    items: {
      type: "object"
      description: "Read shape for a per-(team, skill) scout config.\n\nOne row per `signals-scout-*` skill on the team. The coordinator auto-creates a row\nwhen it discovers a scout skill; this serializer lets agents tune the row."
      required: ["auto_pause_exempt", "consecutive_failure_count", "created_at", "description", "emit", "enabled", "id", "last_run_at", "model", "network_access", "output_destinations", "pause_reason", "run_cron_schedule", "run_interval_minutes", "scout_origin", "skill_name", "status", "status_changed_at", "structured_output_schema"]
      properties: {
        auto_pause_exempt: {
          type: "boolean"
          description: "Whether this scout is exempt from the inactivity sweep, meaning both the `ignored` pause and the `no_output` quiet warning. Set it on watchdog scouts whose value is staying quiet. Also set automatically when someone re-enables a scout the inactivity sweep paused, so the sweep never overrules a person twice."
        }
        consecutive_failure_count: {
          type: "integer"
          description: "How many of this scout's runs have failed in a row. Back to 0 after a successful run or any config edit. At the failure limit the scout pauses itself (`status` becomes `paused_by_system` with `pause_reason` `repeated_failures`) and retries about once a day; a successful retry resumes it, and so does setting `enabled=true`."
        }
        created_at: {
          type: "string"
          format: "date-time"
        }
        description: {
          type: "string"
          description: "Human-readable summary of what this scout investigates, sourced from the scout skill's `description` metadata. Use it for a quick steer on the scout's focus without loading the full skill body. Empty if the skill is not currently present on the team or carries no description."
        }
        emit: {
          type: "boolean"
          description: "Whether the scout writes findings to the inbox. False = dry-run: it runs and logs but emits nothing."
        }
        enabled: {
          type: "boolean"
          description: "Whether this scout runs on its schedule. Disabled scouts are skipped by the coordinator. Derived from `status`: true for `active` and `pending_pause`, false for the paused statuses."
        }
        id: {
          type: "string"
          format: "uuid"
        }
        last_run_at: {
          type: ["string", "null"]
          format: "date-time"
          description: "When the coordinator last dispatched this scout. Null if it has never run."
        }
        model: {
          type: ["string", "null"]
          description: "Optional model id this scout's runs are pinned to, e.g. `claude-opus-4-5`. Must be one of the platform's agent models; an invalid id is rejected with the available ones listed. Null keeps the default model, chosen by the platform. Early access: the pin can only be set on projects enrolled in the scout model preview, and only takes effect there. Set null to clear it."
        }
        network_access: {
          description: "What the scout's sandbox can reach over the network while it runs. `trusted` (the default) restricts runs to the platform's trusted-domain allowlist (PostHog, GitHub, common package registries). `full` lets the scout reach any site, for skills that read external sources such as documentation or papers.\n\n* `trusted` - Trusted domains only\n* `full` - Full"
          type: "object"
        }
        output_destinations: {
          description: "Destinations that receive each finding or report this scout emits. Empty when none is configured."
          type: "object"
        }
        pause_reason: {
          description: "Why the system paused (or warned) this scout: `no_output` (it emitted nothing over the evaluation window), `ignored` (no person engaged with its reports — no view, rating, note, dismissal, or resolution), or `repeated_failures` (consecutive failed runs). Null unless `status` is `pending_pause` or `paused_by_system`.\n\n* `no_output` - No output\n* `ignored` - Ignored\n* `repeated_failures` - Repeated failures"
          type: "object"
        }
        run_cron_schedule: {
          type: ["string", "null"]
          description: "Optional five-field cron expression evaluated in the project timezone, e.g. '30 9 * * *'. Takes precedence over `run_interval_minutes` when set. Null means the rolling interval schedule."
        }
        run_interval_minutes: {
          type: "integer"
          description: "Minutes between runs (30–43200). The scout runs once this interval has elapsed since its last run."
        }
        scout_origin: {
          description: "Where this scout came from: `canonical` for a scout PostHog ships and maintains (seeded from `products/signals/skills/`), or `custom` for one a team hand-authored on this project. Use it to badge built-in vs custom scouts instead of a hardcoded name list. Defaults to `custom` if the skill is not currently present on the team."
          type: "object"
        }
        skill_name: {
          type: "string"
          description: "The `signals-scout-*` skill this config controls. Set at creation, not editable."
        }
        status: {
          description: "Lifecycle status. `active`: runs on its schedule. `pending_pause`: still running, but flagged by the system to pause soon unless something changes (any config edit clears it). `paused_by_system`: paused automatically, see `pause_reason`; set `enabled=true` to resume. `paused_by_user`: switched off by a person and never resumed automatically.\n\n* `active` - Active\n* `pending_pause` - Pending pause\n* `paused_by_system` - Paused by system\n* `paused_by_user` - Paused by user"
          type: "object"
        }
        status_changed_at: {
          type: ["string", "null"]
          format: "date-time"
          description: "When `status` last changed. For `pending_pause` this is when the warning was issued (an `ignored` warning pauses about a week later unless someone engages with the scout's reports — opening one counts; a `no_output` warning only flags the scout); for the paused statuses it is when the scout was paused. Null if the status never changed."
        }
        structured_output_schema: {
          type: ["object", "null"]
          description: "Optional JSON Schema (draft 2020-12) describing ONE structured record this scout produces via `scout-record-output` — e.g. a per-report quality judgment (`{\"type\": \"object\", \"properties\": {\"verdict\": {\"enum\": [\"good\", \"bad\", \"unsure\"]}, \"reason\": {\"type\": \"string\"}}, \"required\": [\"verdict\", \"reason\"]}`). The root must be `\"type\": \"object\"`. Setting a schema turns the structured-output channel on: the run prompt renders the schema and every submitted record is validated against it and recorded in the project as a `$scout_structured_output` event, queryable like any event. The channel also requires emit — a dry-run scout has nowhere to record to. Cardinality is the scout's call (one record per run, one per judged entity, ...). Null = channel off. Setting a schema requires skill-authoring authorization (the `llm_skill:write` scope and skill editor access) since the scout reads it verbatim in its prompt; clearing it needs only the config write. Records validate against the schema in force when the run was dispatched."
        }
        tags: {
          type: "array"
          description: "Free-form labels for grouping the fleet, e.g. `[\"revenue\", \"on-call\"]`. Normalized to lowercase kebab-case (`On Call` and `on_call` both become `on-call`), deduped, and stored sorted; at most 10 tags, each at most 50 characters once normalized. Pass the full desired set — a write replaces the existing tags rather than merging into them. Filter the config list with the `tags` query parameter."
          items: {
            type: "string"
          }
        }
      }
    }
  }
}