---
title: "Forensics"
method: POST
path: "/v1/forensics"
---

# Forensics

`POST /v1/forensics`

## Request

- Base URL: `https://api.alphaassay.com`
- URL: `https://api.alphaassay.com/v1/forensics`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, nullable

## Request body

- ForensicsRequest: Timing forensics input: caller-supplied decision events + candles. Events stay loosely typed here on purpose -- the engine enforces the hard contract (explicit timezones etc.) and returns named findings, so the boundary only guards size and shape.
  - `signal_events` object[], required
  - `ohlcv_by_symbol` object, required
  - `primary_horizon` integer

## Response `200`

Successful Response

- ForensicsOutput
  - `_meta` PublicMeta, required
    - `engine_version` string, required
    - `api_version` string, required
    - `as_of` string, date-time, required
    - `input_digest` string, required
    - `request_digest` string, required
    - `tenant_scope` string, required
    - `tenant_scope_version` string, required
    - `request_id` string, nullable, required
    - `source_identity_digest` string, required
    - `operation` string, required
    - `statefulness` 'pure' | 'public_read' | 'tenant_read' | 'tenant_write', required
    - `not_financial_advice` true, required
    - `disclaimer` string, required
  - `schema` 'signal_forensics.v1', required
  - `verdict` 'leakage_suspected' | 'weak_evidence' | 'insufficient_evidence' | 'no_leakage_detected', required
  - `diagnoses` union[], required
    - union
      - EntryLagDiagnosis
        - `id` 'entry_lag_sweep', required
        - `finding` string, required
        - `severity` 'critical' | 'ok' | 'insufficient_power', required
        - `evidence` EntryLagEvidence, required
          - `events_with_window` IntegerMap: Bounded runtime-keyed map of integer counts.
          - `lag_curve_mean_pct` NumberMap: Bounded runtime-keyed map of finite numbers.
          - `events_per_lag` IntegerMap: Bounded runtime-keyed map of integer counts.
        - `plain_language_explanation` string, required
      - FrontLoadingDiagnosis
        - `id` 'front_loading', required
        - `finding` string, required
        - `severity` 'high' | 'ok' | 'insufficient_power', required
        - `evidence` FrontLoadingEvidence, required
          - `clusters` integer, required
          - `front_loading_share` union
            - integer
            - number
          - `front_loading_share_max` union
            - integer
            - number
          - `pooled_pre_pct` union
            - integer
            - number
          - `pooled_post_pct` union
            - integer
            - number
        - `plain_language_explanation` string, required
      - RandomTimingDiagnosis
        - `id` 'same_symbol_random_timing_placebo', required
        - `finding` string, required
        - `severity` 'high' | 'ok' | 'insufficient_power', required
        - `evidence` RandomTimingEvidence, required
          - `null_window_candidates` integer, nullable
          - `percentile` union
            - integer
            - number
          - `empirical_p_value` union
            - integer
            - number
          - `observed_mean_pct` union
            - integer
            - number
          - `n_null_windows` integer, nullable
          - `seed` integer, nullable
        - `plain_language_explanation` string, required
      - SignRandomizationDiagnosis
        - `id` 'sign_randomization', required
        - `finding` string, required
        - `severity` 'medium' | 'ok' | 'insufficient_power', required
        - `evidence` SignRandomizationEvidence, required
          - `n_clusters` integer, required
          - `empirical_p_value` union
            - integer
            - number
          - `observed_cluster_mean_pct` union
            - integer
            - number
          - `survives` boolean, nullable
        - `plain_language_explanation` string, required
      - ClusterCollapseDiagnosis
        - `id` 'cluster_collapse', required
        - `finding` string, required
        - `severity` 'high' | 'medium' | 'ok' | 'insufficient_power', required
        - `evidence` ClusterCollapseEvidence, required
          - `reported_trades` integer, required
          - `independent_clusters` integer, required
          - `cluster_key` 'utc_calendar_day', nullable
        - `plain_language_explanation` string, required
      - BurstConcentrationDiagnosis
        - `id` 'burst_concentration', required
        - `finding` string, required
        - `severity` 'high' | 'ok' | 'insufficient_power', required
        - `evidence` BurstConcentrationEvidence, required
          - `bars` integer, nullable
          - `min_bars` integer, nullable
          - `burst_events` integer, nullable
          - `calm_events` integer, nullable
          - `n_burst_bars` integer, nullable
          - `burst_mean_pct` union
            - integer
            - number
          - `non_burst_mean_pct` union
            - integer
            - number
        - `plain_language_explanation` string, required
  - `headline` string, required
  - `input_summary` ForensicsInputSummary, required
    - `events_submitted` integer, required
    - `events_valid` integer, required
    - `events_rejected` integer, required
    - `rejected` ForensicsRejectedEvent[], required
      - `index` integer, required
      - `reason` string, required
      - `event` RejectedSignalEvent, required
        - `decision_time` string, nullable
        - `symbol` string, nullable
        - `direction` 'long' | 'short', nullable
        - `confidence` union
          - integer
          - number
    - `distinct_clusters` integer, required
    - `primary_horizon_bars` integer, required
  - `disclaimer` string, required

## Other responses

- `401`: Request could not be completed
- `402`: Request could not be completed
- `403`: Request could not be completed
- `409`: Request could not be completed
- `413`: Request could not be completed
- `422`: Request could not be completed
- `429`: Request rate limit exceeded
- `500`: Internal execution failure
- `503`: Request could not be completed

---

[API](https://skmtc.dev/alphaassay/apis/alphaassay-api.md) · [All operations](https://skmtc.dev/alphaassay/apis/alphaassay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alphaassay/apis/alphaassay-api/revisions/cdbc99b01a7e?raw)