POST: Generate Forecast Timelines

Erin Conry

https://api.bitsighttech.com/ratings/v1/companies/company_guid/risk-remediation-plan/forecast-timelines

Generate grade projection timelines for one or more risk vectors based on a remediation scenario. Returns projected grade state at future effective dates, assuming findings are remediated according to the specified strategy and due date. See Running a Risk Remediation Forecast for details.

Request Body

The request body is an object keyed by risk vector slug. Include only the vectors you want to forecast. Each value is a per-vector configuration object.

Field	Description
{risk_vector}.due_date String [date] — Required	Target remediation date in `YYYY-MM-DD` format. The forecast projects grades assuming all findings are resolved by this date.
{risk_vector}.strategy String — Required	Remediation pacing strategy. `linear` distributes findings evenly over time; `on_date` assumes all findings are fixed on the due date.
{risk_vector}.findings Array — Required for most vectors	List of `rolledup_observation_id` values to include in the forecast. Used for all vectors except Critical Vulnerability Management.
{risk_vector}.grades Object — Required for Critical Vulnerability Management	Grade bucket counts for Critical Vulnerability Management forecasts. Keys: `bad`, `warn`, `fair` (each an integer count of findings in that bucket).

Example Request

curl -X POST https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/risk-remediation-plan/forecast-timelines \
  -u api_token: \
  -H "Content-Type: application/json" \
  -d '{
    "web_appsec": {
      "due_date": "2026-12-31",
      "strategy": "linear",
      "findings": ["f04XjmWh4Vfc4ghT18Dfxg==", "T-p7DmMtOkW7CjWDpJeXw=="]
    },
    "patching_cadence": {
      "due_date": "2026-12-31",
      "strategy": "on_date",
      "grades": {"bad": 5, "warn": 10, "fair": 15}
    }
  }'

Example Response

{
  "web_appsec": [
    {
      "ACTIVE_COUNT": 5,
      "ACTIVE_SUM": 12.3,
      "effective_date": "2026-04-15"
    }
  ],
  "patching_cadence": [
    {
      "ACTIVE_COUNT": 12,
      "RMD_MEAN": 14.2,
      "RMD_COUNT": 2.5,
      "effective_date": "2026-04-15"
    }
  ]
}

Response Attributes

Field	Description
{risk_vector}[] Array	Array of timeline projection entries for this risk vector. One entry per projected effective date.
{risk_vector}[].effective_date String [date]	The projected date this timeline entry corresponds to.
{risk_vector}[].ACTIVE_COUNT Integer	Number of active findings remaining at this effective date.
ssl_certificates[].good / bad / warn / fair / neutral Integer	Count of findings at each grade level for TLS/SSL Certificates at this effective date.
patching_cadence[].RMD_MEAN Number	Mean remediation duration across active findings. Critical Vulnerability Management only.
patching_cadence[].RMD_COUNT Number	Projected remediation count. Critical Vulnerability Management only.

Status Codes

200 – Okay: Everything worked as expected.
401 – Unauthorized: No valid API token was provided.
403 – Permission Denied: You do not have permission to access this resource.
422 – Unprocessable Entity: A request body field is missing or invalid.