Run a cohort comparison study (record_occurrences)
run_cohortExecute a research query to compare treatment and baseline outcomes, returning canonical cohort results with multi-horizon summaries over all occurrences.
Instructions
Execute a research_query.v2 document as a predicate-complement comparison and return canonical cohort_result.v2 bytes: what followed the condition (the treatment side, byte-identical to the run_scan outcomes_summary for the same document) vs what followed every OTHER eligible bucket where the full predicate was FALSE (the baseline), each as the same 30m/1h/4h/24h return + MFE/MAE summary over ALL occurrences. WHERE-ONLY: a sequence document is refused with 422 COHORT_SEQUENCE_UNSUPPORTED (run it as an ordinary run_scan instead). The bytes carry NO ratios, lift, averages or significance - you compare the two distributions yourself. This is not covariate matching: treatment/baseline identities, different observation units, dedupe difference, and denominator arithmetic ship in the result with three mandatory caveats. Both sides honour the completeness rule: an occurrence closer to the end of recorded data than a horizon has that horizon ABSENT - quote present, not total, as the denominator. CONTRACT (relay to the user): Echo the exact document and the reproducibility key to the user with the result. Rates come from outcomes_summary over all occurrences; page rows are examples, never the denominator. Outcome fields cannot be filtered; expect OUTCOME_IN_PREDICATE if tried. A rerun of the same document is served from cache (X-Research-Cache: hit) in its own cohort namespace; reruns and 304 revalidations are free.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | A complete research_query.v2 document (target record_occurrences, WHERE-ONLY - no sequence). Call list_features for the grammar; do not invent field names. | |
| full_counts | No | True returns the engine's verbatim canonical bytes, including any zero-count instrument in counts_by_symbol. Default omits zero-count entries when present. | |
| if_none_match | No | An ETag from a previous cohort run to revalidate: identical data answers 304 and spends nothing. Pass it back verbatim (it may be weak, W/"..."). |