Skip to main content

GET /v1/signals/volatility

Return the OMNI volatility score with transparent factor breakdown and freshness metadata
Audience: application and coding agent.

Canonical metadata

  • requestId
  • traceparent
  • provenance
  • freshness
  • methodologyVersion
  • factors
  • degradedReasons

Example request

curl -X GET \
  -H "x-api-key: $OMNI_DATASTREAM_API_KEY" \
  -H "omni-version: 2026-03-19" \
  "https://api.secapi.ai/v1/signals/volatility?ticker=AAPL"

Example response

{
  "object": "derived_signal",
  "id": "sig_vol_aapl",
  "createdAt": "2026-03-18T16:00:00.000Z",
  "livemode": false,
  "signalKey": "omni_volatility_score",
  "methodologyVersion": "2026-03-17.2",
  "entityId": "ent_aapl",
  "ticker": "AAPL",
  "cik": "0000320193",
  "companyName": "Apple Inc.",
  "asOf": "2026-03-18T16:00:00.000Z",
  "score": 38.6,
  "band": "moderate",
  "confidence": "medium",
  "summaryMd": "## OMNI Volatility Score for Apple Inc.\n\nScore: 38.6 (moderate). Strongest contributor: Disclosure Intensity.",
  "factors": [
    {
      "key": "disclosure_intensity",
      "label": "Disclosure Intensity",
      "score": 42,
      "weight": 0.35,
      "value": 4,
      "explanation": "More frequent high-signal SEC disclosures tend to coincide with elevated uncertainty and event risk."
    }
  ],
  "degradedReasons": [
    "No recent insider transactions were available, so the insider-imbalance factor is low-confidence."
  ],
  "freshness": {
    "status": "degraded",
    "updatedAt": "2026-03-18T16:00:00.000Z",
    "reason": "No recent insider transactions were available, so the insider-imbalance factor is low-confidence."
  },
  "requestId": "req_example_123",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "provenance": {
    "source": "sec",
    "accessionNumber": null,
    "filingUrl": "https://www.sec.gov/edgar/searchedgar/companysearch",
    "retrievedAt": "2026-03-18T16:00:00.000Z",
    "parserVersion": "2026-03-16.1"
  }
}

Give this prompt to your agent

Failure posture

  • treat non-2xx responses as contract-aware failures, not free-form errors
  • preserve requestId and traceparent in logs and downstream reports
  • if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff