FLfloqer
ackDB

Preview a DRAFT definition (unsaved)

Validates + compiles the draft body and returns the live population's score distribution — the builder histogram. Percentile drafts rank inline (exact), so nothing needs saving first. percentilePopulation: "active" drafts histogram the active rows only; population/excluded report the split (#432).

post/api/v1/ackdb/scores/preview

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Request body

scoreKeystring required

Immutable slug → the sc__<scoreKey> column. Single underscores only.

namestring required
descriptionstring nullable
grain'company' | 'person' required

Immutable after create.

normalization'absolute' | 'percentile'

absolute (default): 100 × points / max possible, clamped. percentile: rank within THIS grain's population (strictly-below semantics — a no-data row is the 0th percentile).

percentilePopulation'all' | 'active'

Percentile definitions only (#432) — 400 with absolute normalization. all (default): rank against the whole grain population (today's behavior). active: rank only against rows where at least one non-trait criterion fired (an event:/convergence/contacts/company: criterion contributed nonzero points) — on sparse books the empty rows stop being the yardstick. Excluded rows still serve a score of 0 (never NULL) and take whatever lt label band covers 0.

scopeSegmentIdstring nullable

SCOPE (#443): score ONLY the members of this saved segment. Absent/null = the whole grain (every definition before this feature). Rows outside the segment read NULL in sc__<key> and sc__<key>__label — not 0 — and are excluded from the percentile population, the preview histogram and the history sweep. ANY segment grain is legal for either score grain: a contact/person segment scoping a company score means 'the companies of those people', a company segment scoping a person score means 'the people with an active edge at those companies'. Derived segments are legal. 400s when the segment does not exist, or when its filter (or its base's) references a SCOPED score — a scored population may only be defined by whole-grain scores, which is what makes a scoring cycle impossible.

isPrimaryboolean

One primary per grain (server-enforced hand-off).

enabledboolean

Example request

{
  "scoreKey": "pql",
  "name": "PQL score",
  "groups": [
    {
      "key": "fit",
      "weight": 0.4
    }
  ],
  "criteria": [
    {
      "field": "event:slack.message",
      "valueField": "employee_count"
    }
  ],
  "labels": [
    {
      "label": "Excellent"
    }
  ]
}

Response

The score distribution.

totalinteger required

Rows in the histogram (Σ bucket counts) — equals population.

populationinteger required

Rows the histogram ranks (#432): the active population for percentilePopulation: "active" definitions, else all rows of the grain (or, for a SCOPED definition, all rows of its scope).

outOfScopeinteger required

Rows of the grain the definition does not score AT ALL (#443) — outside its scope segment; 0 when unscoped. Distinct from excluded, which counts rows that ARE scored but not ranked. Together they let a builder say "ranks 412 of 20,104 companies".

excludedinteger required

Rows outside the ranking population (#432) — 0 unless percentilePopulation: "active". The builder renders "ranked among N active · M excluded".

Changes

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