Worked examples

Four documents that cover most real questions.

1. The engulfing sequence (outcome asks, honestly)

"Bullish engulfing candles that pumped 5% after" is an outcome ask, and outcomes can never be filters. Stated honestly it is a SEQUENCE: the engulfing, then the move, within a window. The anchor becomes the completion of the compound pattern, and outcomes_summary reports what followed ALL engulfings, not just the winners.

Often you do not need the sequence at all: scan the engulfing alone and read outcomes_summary. Since record_result.v3 it carries 4h and 24h horizons (mfe_4h, mfe_24h, plus returns and MAE) with thresholds up to ±20% - so "how many reached +5% within 24h, and with how much drawdown" is answered by the summary over EVERY engulfing, denominator attached. Matches too close to the record edge for a horizon are counted absent, never truncated.

{
  "schema_version": "research_query.v2",
  "normalization_version": "archive_normalization.v1",
  "feature_version": "feature_defs.v1",
  "target": "record_occurrences",
  "where": { "all": [
    ["times.anchor_time", "between", ["2026-07-01T00:00:00Z", "2026-07-15T00:00:00Z"]]
  ]},
  "sequence": {
    "steps": [
      { "all": [["feature.candle_engulfing_15m", "eq", "bullish"]] },
      { "all": [["feature.ret_1h", "gte", 0.05]] }
    ],
    "within": "4h"
  },
  "sort": ["times.anchor_time", "asc"],
  "page": { "limit": 50, "cursor": null }
}

2. A where-scan (toxicity + one-sided books)

Plain conjunctive conditions over the whole universe: where was flow toxic while the book leaned hard to one side?

{
  "schema_version": "research_query.v2",
  "normalization_version": "archive_normalization.v1",
  "feature_version": "feature_defs.v1",
  "target": "record_occurrences",
  "where": { "all": [
    ["times.anchor_time", "between", ["2026-07-09T00:00:00Z", "2026-07-16T00:00:00Z"]],
    ["feature.vpin", "gte", 0.7],
    ["feature.book_imbalance_pctrank", "gte", 0.9]
  ]},
  "sort": ["times.anchor_time", "desc"],
  "page": { "limit": 50, "cursor": null }
}

7 days x 660 symbols / 5000 = 1 unit.

3. From a moment (snapshot, then scan)

Point at a moment and read the registry as-of that bucket: every feature value, window aggregates, fired rulebook ids. Turn what you see into clauses and scan for every other time it looked like that.

curl -s "https://app.edgedepth.com/api/v1/research/snapshot?symbol=ethusdt&t=2026-07-14T18:05:00Z" \
  -H "Authorization: Bearer edk_live_YOUR_KEY"

The snapshot is a cacheable artifact with its own reproducibility headers; it never executes a query. Selection discipline still applies: if you picked the moment BECAUSE it moved, the follow-up scan is the corrective - expect the pattern to deflate over all occurrences. That is the product working.

4. Paging

Page 1 answers with counts, outcomes_summary (over ALL occurrences) and up to 50 rows plus a cursor. Continue by re-sending the SAME document with the cursor filled in:

"page": { "limit": 50, "cursor": "CURSOR_FROM_PREVIOUS_RESPONSE" }

Two rules. Never construct cursors: they are opaque. And if X-Dataset-Revision changes between pages, the nightly append landed: the result set changed, restart from page 1. The canonical hash ignores the cursor, so every page shares one reproducibility key and caches per (key, cursor).

Interpret (optional scope)

With research:interpret, prose goes in and a PROPOSED document comes out - labeled proposal: true, never executed. Re-submit its document to POST /api/v1/research/query; your re-submission IS the confirm gate.

curl -s https://app.edgedepth.com/api/v1/research/interpret \
  -H "Authorization: Bearer edk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "vpin above 0.7 then a liquidation surge within 30m on majors last week"}'