ClusterBuy

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/algoum-de/json-schema/algoum-de-cluster-buy-schema.json",
  "title": "ClusterBuy",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/algoum-de-api-openapi.json#/components/schemas/ClusterBuy",
  "type": "object",
  "required": [
    "ticker",
    "cik",
    "insider_count",
    "window",
    "as_of",
    "roles",
    "min_insiders",
    "uniform_price",
    "rule_version",
    "sec_known_at",
    "evidence"
  ],
  "properties": {
    "ticker": {
      "type": "string"
    },
    "cik": {
      "type": "string"
    },
    "insider_count": {
      "type": "integer",
      "description": "Number of independent insiders with a buy in the window."
    },
    "total_shares": {
      "type": "number"
    },
    "total_value": {
      "$ref": "#/$defs/Money",
      "description": "Sum of shares times price, in US dollars. Purchases priced in another currency are left out of this sum, but still count towards `insider_count` and `total_shares`."
    },
    "window": {
      "type": "string"
    },
    "as_of": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "Requested point in time; `null` when the window ends today. The stream always sends `null`."
    },
    "roles": {
      "type": "array",
      "uniqueItems": true,
      "description": "Effective role filter in alphabetical order; empty means all roles.",
      "items": {
        "$ref": "#/$defs/InsiderRole"
      }
    },
    "first_buy_date": {
      "type": "string",
      "format": "date"
    },
    "last_buy_date": {
      "type": "string",
      "format": "date"
    },
    "min_insiders": {
      "type": "integer",
      "minimum": 1,
      "description": "Requested minimum number of distinct insider names."
    },
    "uniform_price": {
      "type": "boolean",
      "description": "All counted buyers with a price bought at the same price (at least three, highest at most 0.1 % above lowest) - usually a joint purchase such as a private placement or a reinvestment plan rather than independent decisions. See `exclude_uniform_price`."
    },
    "rule_version": {
      "type": "string",
      "description": "Version of the name-based, transaction-date aggregation rule.",
      "enum": [
        "cluster-buys-v1"
      ]
    },
    "sec_known_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Earliest stored filing time at which the requested number of distinct buyers was known for the current window's transactions. Null if any contributing filing lacks a usable time. Historical archive times may have only date-level precision. Not a historical API publication time or a reconstructed rolling-window alert."
    },
    "evidence": {
      "type": "array",
      "description": "Contributing filing/buyer pairs without duplicate transaction lines, sorted by filed_at, filing_id and insider_name; missing times last.",
      "items": {
        "$ref": "#/$defs/ClusterBuyEvidence"
      }
    }
  },
  "$defs": {
    "ClusterBuyEvidence": {
      "type": "object",
      "required": [
        "filing_id",
        "insider_name",
        "role",
        "reporting_owners",
        "filed_at",
        "source_url"
      ],
      "properties": {
        "filing_id": {
          "type": "string",
          "description": "Accession number of a contributing filing."
        },
        "insider_name": {
          "type": "string",
          "description": "First reporting owner's name used by the existing buyer count."
        },
        "role": {
          "$ref": "#/$defs/InsiderRole"
        },
        "role_detail": {
          "type": "string",
          "description": "Reported job title or relationship of the counted first owner, when available."
        },
        "reporting_owners": {
          "type": "array",
          "description": "Stored reporting owners, including their available CIKs and roles. Additional owners do not increase the buyer count or qualify an excluded first owner. Empty if no owners were stored; no IDs are inferred.",
          "items": {
            "$ref": "#/$defs/ReportingOwner"
          }
        },
        "filed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Stored SEC filing time in Eastern Time; null if unavailable, possibly date-level for archives."
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "Link to the source SEC filing."
        }
      }
    },
    "InsiderRole": {
      "type": "string",
      "description": "Relationship of the reporter to the issuer, taken from the four check boxes of the Form 4 section “Relationship of Reporting Person(s) to Issuer”. `other` stands for the *Other* box; the label entered there (e.g. “Trustee”) is in `role_detail`.",
      "enum": [
        "officer",
        "director",
        "10%-owner",
        "other"
      ]
    },
    "Money": {
      "type": "object",
      "description": "Monetary amount with currency.",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "number"
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 code, except `GBX` for prices in British pence."
        }
      }
    },
    "ReportingOwner": {
      "type": "object",
      "description": "A reporting person or entity of a §16 filing.",
      "required": [
        "name",
        "cik",
        "role"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "cik": {
          "type": "string"
        },
        "role": {
          "$ref": "#/$defs/InsiderRole"
        },
        "role_detail": {
          "type": "string",
          "description": "Free text from the filing about the role: for `officer` the job title, for `other` the kind of relationship."
        }
      }
    }
  }
}