Skip to main content
POST
/
api
/
v1
/
backchannel
/
risk
/
scenario_portfolio_analysis
cURL
curl --request POST \
  --url https://tilt.io/api/v1/backchannel/risk/scenario_portfolio_analysis \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "scenario_description": "<string>",
  "portfolio_weights": {},
  "as_of_date": "<string>",
  "flat_scenarios": false,
  "search_for_context": true,
  "include_security_details": true,
  "aggregate_scenarios": false,
  "force_regenerate": false
}
'
{
  "success": true,
  "scenario_description": "<string>",
  "as_of_date": "<string>",
  "scenario_tree": [
    {
      "probability": 50,
      "title": "<string>",
      "description": "<string>",
      "sub_scenarios": [
        {}
      ],
      "macro_shocks": [
        {
          "indicator": "<string>",
          "impact": 123
        }
      ]
    }
  ],
  "expected_portfolio_return_pct": 123,
  "portfolio_summary": {
    "num_securities": 123,
    "total_weight": 123,
    "num_scenarios": 123,
    "num_leaf_scenarios": 123
  },
  "cache_hit": true,
  "generated_at": "<string>",
  "leaf_scenarios": [
    {
      "path": [
        "<string>"
      ],
      "joint_probability_pct": 123,
      "title": "<string>",
      "description": "<string>",
      "macro_shocks": {},
      "portfolio_return_pct": 123,
      "portfolio_expected_return_pct": 123,
      "contribution_to_expected_return_pct": 123,
      "top_movers": [
        {
          "tilt_id": "<string>",
          "weight": 123,
          "expected_return_pct": 123,
          "contribution_to_portfolio_pct": 123,
          "factor_contributions": {},
          "ticker": "<string>",
          "company_name": "<string>"
        }
      ],
      "security_details": [
        {
          "tilt_id": "<string>",
          "weight": 123,
          "expected_return_pct": 123,
          "contribution_to_portfolio_pct": 123,
          "factor_contributions": {},
          "ticker": "<string>",
          "company_name": "<string>"
        }
      ]
    }
  ],
  "scenario_level_results": [
    {
      "title": "<string>",
      "description": "<string>",
      "probability_pct": 123,
      "portfolio_return_mean_pct": 123,
      "portfolio_return_std_pct": 123,
      "macro_shocks": [
        {
          "indicator": "<string>",
          "mean": 123,
          "std": 123
        }
      ],
      "sub_scenario_count": 123
    }
  ],
  "context_articles": [
    "<string>"
  ],
  "context_article_ids": [
    "<string>"
  ],
  "warnings": [
    "<string>"
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.tilt.pro/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

X-Api-Key
string
header
required

Body

application/json
scenario_description
string
required

Plain English scenario description (e.g., 'Trump invades Greenland')

portfolio_weights
object
required

Mapping of tilt_asset_id to portfolio weight

as_of_date
string | null

Analysis date in YYYY-MM-DD format. Defaults to today.

Pattern: ^\d{4}-\d{2}-\d{2}$
flat_scenarios
boolean
default:false

If true, generate flat scenarios (no sub-scenarios) where each scenario directly contains its macro_shocks. Recommended for simpler UIs.

search_for_context
boolean
default:true

Whether to search for relevant background articles to improve scenario quality

include_security_details
boolean
default:true

Include per-security breakdown for each scenario

aggregate_scenarios
boolean
default:false

If true, return results aggregated at the top-level scenario instead of sub-scenario level

force_regenerate
boolean
default:false

If true, bypass scenario cache and regenerate from scratch

Response

200 - application/json

AI-generated scenario tree with portfolio impact analysis

success
boolean
required
scenario_description
string
required
as_of_date
string
required
scenario_tree
object[]
required

Full probability tree. Flat when flat_scenarios=true, nested with sub_scenarios when false.

expected_portfolio_return_pct
number
required

Probability-weighted expected portfolio return across all leaf scenarios (0.01 = 1%)

portfolio_summary
object
required

Counts of scenarios, leaf scenarios, and securities analyzed

cache_hit
boolean
required

Whether the scenario tree was served from cache (true) or freshly generated (false)

generated_at
string
required

ISO timestamp of when the result was generated

leaf_scenarios
object[] | null

All leaf scenarios with portfolio impacts. Omitted when aggregate_scenarios=true.

scenario_level_results
object[] | null

Scenario-level aggregated results. Only present when aggregate_scenarios=true.

context_articles
string[] | null

Headlines of background articles used during scenario generation

context_article_ids
string[] | null

Point IDs of context articles. Use POST /scenarios/batch to fetch full details.

warnings
string[] | null

Warnings about input data (e.g., unknown tilt_ids skipped)