MultiStateScopeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/goodleads-club/json-schema/goodleads-club-multi-state-scope-request-schema.json",
  "title": "MultiStateScopeRequest",
  "description": "The scope half of a fan-out: which records, across which states.\n\nShared by the preview and the trigger so the states and counts an operator\napproves are resolved by exactly one piece of code. Deliberately carries NO\nstage list — which states a selection touches, and how many records it\nmatches in each, does not depend on what you intend to run on them.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/goodleads-club-openapi.json#/components/schemas/MultiStateScopeRequest",
  "properties": {
    "states": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "States",
      "description": "Restrict the fan-out to these states. Omit to run every state the selection touches. It narrows, never widens: a state named here that the selection does not touch is simply absent from the result."
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Limit",
      "description": "PER-STATE cap, not a total — `limit=100` across 5 states runs up to 500 records. One shared budget would have to pick which state gets starved; capping each leg is the predictable reading of 'take 100 from each'."
    },
    "entity_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Entity Id",
      "description": "Comma/space/newline-separated UUIDs or GLIDs that may span states. Grouped by state, one run per state. Mutually exclusive with `filters`."
    },
    "filters": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Filters",
      "description": "Filter expression, same shape as POST /api/v1/leads/browse, WITHOUT a state clause — the fan-out supplies each leg's own. Mutually exclusive with `entity_id`."
    },
    "include_non_operating": {
      "type": "boolean",
      "title": "Include Non Operating",
      "description": "Only meaningful with `filters`. Mirrors Browse's own default so the per-state counts match the number on the button the operator pressed — see `TriggerRequest.include_non_operating`.",
      "default": false
    },
    "include_existing": {
      "type": "boolean",
      "title": "Include Existing",
      "description": "Only meaningful with `filters`. See `TriggerRequest.include_existing`.",
      "default": false
    },
    "include_registrations": {
      "type": "boolean",
      "title": "Include Registrations",
      "description": "Deprecated alias of include_existing (kept one release so saved requests resolve).",
      "default": false,
      "deprecated": true
    }
  },
  "additionalProperties": false,
  "type": "object"
}