> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrubbe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blast Radius API: calculate and query impact reports

> Calculate blast radius from a trigger or service, list persisted impact reports, retrieve workspace risk summaries, and look up reports by ID.

The Blast Radius API helps you understand how far a failure can spread — before it happens or while it is unfolding. Submit a trigger or service identifier and Scrubbe traverses the downstream dependency graph to estimate which services, regions, and user populations are at risk. Reports are persisted so you can track risk over time, compare assessments across incidents, and feed impact data into incident creation or playbook selection.

<Note>
  All endpoints require `Authorization: Bearer <token>`. Provide either `triggerId` or `serviceId` in the calculate request body — not both.
</Note>

**Base path:** `https://your-api-domain.com/api/v1/blast-radius`

***

## Calculate blast radius

Trigger a blast radius calculation for a given trigger or service. Scrubbe traverses the dependency graph and returns an impact assessment covering affected services, estimated user population, and risk scores.

`POST https://your-api-domain.com/api/v1/blast-radius/calculate`

<ParamField body="triggerId" type="string">
  ID of the event or alert trigger to calculate impact for. Provide either `triggerId` or `serviceId`.
</ParamField>

<ParamField body="serviceId" type="string">
  ID of the service to model as the failure origin. Provide either `triggerId` or `serviceId`.
</ParamField>

<ParamField body="environment" type="string">
  Constrain the calculation to a specific environment (e.g. `"production"`, `"staging"`).
</ParamField>

<ParamField body="depth" type="number" default="3">
  Maximum dependency traversal depth. Higher values are more thorough but take longer to compute.
</ParamField>

<CodeGroup>
  ```bash cURL — by trigger theme={null}
  curl -X POST https://your-api-domain.com/api/v1/blast-radius/calculate \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "triggerId": "TRG-20260522-0041",
      "environment": "production"
    }'
  ```

  ```bash cURL — by service theme={null}
  curl -X POST https://your-api-domain.com/api/v1/blast-radius/calculate \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "serviceId": "svc-payments",
      "environment": "production",
      "depth": 4
    }'
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    'https://your-api-domain.com/api/v1/blast-radius/calculate',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer <token>',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        serviceId: 'svc-payments',
        environment: 'production',
        depth: 4,
      }),
    }
  );
  const { data } = await resp.json();
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      'https://your-api-domain.com/api/v1/blast-radius/calculate',
      headers={'Authorization': 'Bearer <token>'},
      json={
          'serviceId': 'svc-payments',
          'environment': 'production',
          'depth': 4,
      },
  )
  print(resp.json())
  ```
</CodeGroup>

<ResponseField name="reportId" type="string" required>Unique identifier for this blast radius report.</ResponseField>
<ResponseField name="triggerId" type="string">Trigger ID used as the calculation origin, if provided.</ResponseField>
<ResponseField name="serviceId" type="string">Service ID used as the calculation origin, if provided.</ResponseField>
<ResponseField name="environment" type="string">Environment the calculation was scoped to.</ResponseField>

<ResponseField name="affectedServices" type="object[]">
  Services within the blast radius, ordered by risk score descending.

  <Expandable title="properties">
    <ResponseField name="serviceId" type="string">Service identifier.</ResponseField>
    <ResponseField name="name" type="string">Human-readable service name.</ResponseField>
    <ResponseField name="riskScore" type="number">Impact probability from `0` (no risk) to `1` (certain impact).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="estimatedUserImpact" type="string">Plain-language description of the estimated affected user population.</ResponseField>
<ResponseField name="overallRiskScore" type="number">Aggregate risk score for the entire blast radius, from `0` to `1`.</ResponseField>
<ResponseField name="calculatedAt" type="string" required>ISO 8601 timestamp of the calculation.</ResponseField>

<Tip>
  Run a blast radius calculation at the start of a major incident to quickly populate the `blastRadius` field on the incident ticket and inform stakeholder communications.
</Tip>

***

## List blast radius reports

Returns a paginated list of all blast radius reports for the workspace, ordered by calculation date descending.

`GET https://your-api-domain.com/api/v1/blast-radius`

<ParamField query="page" type="number" default="1">Page number.</ParamField>
<ParamField query="limit" type="number" default="20">Items per page (max 100).</ParamField>
<ParamField query="serviceId" type="string">Filter reports by origin service.</ParamField>
<ParamField query="environment" type="string">Filter by environment.</ParamField>

```bash cURL theme={null}
curl "https://your-api-domain.com/api/v1/blast-radius?serviceId=svc-payments" \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="data" type="object[]">Array of blast radius report summaries.</ResponseField>
<ResponseField name="total" type="number">Total matching report count.</ResponseField>

***

## Get risk summary

Returns an aggregated risk summary across all services in the workspace — overall risk distribution, top highest-risk services, and trend data. Use this for dashboard widgets and reliability reviews.

`GET https://your-api-domain.com/api/v1/blast-radius/risk-summary`

```bash cURL theme={null}
curl https://your-api-domain.com/api/v1/blast-radius/risk-summary \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="totalServicesAnalysed" type="number">Number of services with at least one blast radius report.</ResponseField>

<ResponseField name="highRiskServices" type="object[]">
  Services with an average risk score above `0.75`, ordered by score descending.

  <Expandable title="properties">
    <ResponseField name="serviceId" type="string">Service identifier.</ResponseField>
    <ResponseField name="name" type="string">Human-readable service name.</ResponseField>
    <ResponseField name="averageRiskScore" type="number">Average risk score across all reports for this service.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="riskDistribution" type="object">
  Count of services by risk tier.

  <Expandable title="properties">
    <ResponseField name="high" type="number">Services with average risk score ≥ 0.75.</ResponseField>
    <ResponseField name="medium" type="number">Services with average risk score between 0.4 and 0.74.</ResponseField>
    <ResponseField name="low" type="number">Services with average risk score below 0.4.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="lastUpdated" type="string">ISO 8601 timestamp of the most recent calculation included in the summary.</ResponseField>

***

## Get reports for a trigger

Returns all blast radius reports associated with a specific trigger ID.

`GET https://your-api-domain.com/api/v1/blast-radius/trigger/:triggerId`

<ParamField path="triggerId" type="string" required>
  The trigger ID.
</ParamField>

```bash cURL theme={null}
curl https://your-api-domain.com/api/v1/blast-radius/trigger/TRG-20260522-0041 \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="data" type="object[]">Array of blast radius reports linked to the given trigger.</ResponseField>

***

## Get a report by ID

Returns the full detail for a single blast radius report, including all affected services and risk scores.

`GET https://your-api-domain.com/api/v1/blast-radius/:id`

<ParamField path="id" type="string" required>
  The blast radius report ID.
</ParamField>

```bash cURL theme={null}
curl https://your-api-domain.com/api/v1/blast-radius/BR-20260522-0018 \
  -H "Authorization: Bearer <token>"
```

<ResponseField name="reportId" type="string" required>Unique report identifier.</ResponseField>
<ResponseField name="triggerId" type="string">Trigger origin, if the report was calculated from a trigger.</ResponseField>
<ResponseField name="serviceId" type="string">Service origin, if the report was calculated from a service.</ResponseField>
<ResponseField name="environment" type="string">Scoped environment.</ResponseField>

<ResponseField name="affectedServices" type="object[]">
  Services within the blast radius, ordered by risk score.

  <Expandable title="properties">
    <ResponseField name="serviceId" type="string">Service identifier.</ResponseField>
    <ResponseField name="name" type="string">Human-readable service name.</ResponseField>
    <ResponseField name="riskScore" type="number">Impact probability from `0` to `1`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="estimatedUserImpact" type="string">Plain-language estimate of affected users.</ResponseField>
<ResponseField name="overallRiskScore" type="number">Aggregate risk score, from `0` to `1`.</ResponseField>
<ResponseField name="calculatedAt" type="string" required>ISO 8601 timestamp of the calculation.</ResponseField>