screener_response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/falpha-ai/json-schema/falpha-ai-screener-response-schema.json",
  "title": "screener_response",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/falpha-ai-openapi.json#/components/schemas/screener_response",
  "properties": {
    "as_of": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "As Of",
      "description": "Model-run date of the screened signal cube (latest available)"
    },
    "period": {
      "type": "string",
      "title": "Period"
    },
    "regime": {
      "type": "string",
      "title": "Regime"
    },
    "direction": {
      "type": "string",
      "title": "Direction",
      "description": "Direction filter applied: buy, sell, or any"
    },
    "sector": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sector",
      "description": "Sector filter applied, if any"
    },
    "rank_by": {
      "type": "string",
      "title": "Rank By",
      "description": "Ranking key: confidence or quality"
    },
    "count": {
      "type": "integer",
      "title": "Count"
    },
    "scanned": {
      "type": "integer",
      "title": "Scanned",
      "description": "Docs considered from the cube date (after sector filter, before top truncate). `top` only caps `results` — DB work is O(scanned), so top=10 and top=50 cost the same."
    },
    "universe": {
      "type": "string",
      "title": "Universe",
      "description": "Which set was ranked: 'covered_universe' (every covered ticker, after any sector filter), 'plan_cohort' (only the tickers the caller's pay-as-you-go plan covers today) or 'professional_universe' (the S&P 500, S&P 400 and Russell 2000 members a Professional plan covers). A ranking over a plan's set is complete for that set and is NOT a ranking of the universe.",
      "default": "covered_universe"
    },
    "universe_note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Universe Note",
      "description": "Plain statement of what was ranked, present whenever `universe` is not the full covered universe."
    },
    "results": {
      "items": {
        "$ref": "#/$defs/screener_row"
      },
      "type": "array",
      "title": "Results"
    }
  },
  "type": "object",
  "required": [
    "period",
    "regime",
    "direction",
    "rank_by",
    "count",
    "scanned",
    "results"
  ],
  "$defs": {
    "screener_row": {
      "properties": {
        "ticker": {
          "type": "string",
          "title": "Ticker"
        },
        "date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Date"
        },
        "signal": {
          "type": "string",
          "title": "Signal",
          "description": "buy or sell (sign of the signal score)"
        },
        "confidence": {
          "type": "number",
          "title": "Confidence",
          "description": "Absolute signal score used for ranking"
        },
        "quality": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quality",
          "description": "Sharpe-ratio quality proxy for the row (null when unavailable)"
        }
      },
      "type": "object",
      "required": [
        "ticker",
        "signal",
        "confidence"
      ],
      "title": "screener_row"
    }
  }
}