Skip to main content

​
Overview

The Backchannel API lets you answer two core questions about a portfolio:
  1. “What would happen to my portfolio if X occurred?” — Describe any scenario in plain English and get a probability-weighted impact analysis.
  2. “How does this news event affect my holdings?” — Search curated news scenarios and compute portfolio exposure against them.
  3. “What happens if macro conditions change?” — Run what-if analysis with specific macro factor shocks (USD strength, oil prices, etc.).
All workflows require a portfolio expressed as a map of tilt_asset_id → weight. This guide walks through resolving tickers, building portfolio weights, and calling the scenario and risk endpoints.

​
Step 1: Resolve Tickers to Tilt Asset IDs

All portfolio-related endpoints accept weights keyed by Tilt Asset ID — an internal identifier for each security. Use the Search Tickers endpoint to resolve symbols. 
curl -X GET "https://api.tilt.io/api/v1/tickers/search?symbols=AAPL,MSFT,NVDA" \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "count": 6,
  "results": [
    {
      "symbol": "AAPL",
      "name": "Apple, Inc.",
      "exchange": "NAS",
      "ticker_type": "common_stock",
      "tilt_asset_id": "MH33D6-R"
    },
    {
      "symbol": "AAPL",
      "name": "Apple, Inc.",
      "exchange": "TSE",
      "ticker_type": "dr",
      "tilt_asset_id": "W0R2RY-R"
    },
    ...
  ]
}
A symbol may return multiple results across exchanges (e.g. NAS and TSE listings). Filter by ticker_type: "common_stock" and the relevant exchange to get the primary US listing.
Extract the tilt_asset_id from each result. View API Reference →
You can resolve multiple symbols in a single call by passing a comma-separated list. Cache the mapping — tilt asset IDs are stable identifiers that don’t change.

​
Step 2: Build Portfolio Weights

Construct a portfolio_weights object mapping each tilt_asset_id to a decimal weight (summing to 1.0): 
{
  "MH33D6-R": 0.40,
  "P8R3C2-R": 0.35,
  "K7TPSX-R": 0.25
}
Weights should sum to 1.0. If they don’t, the API will still work but exposure calculations will be proportional to the weights provided.
This portfolio_weights object is reused across all the endpoints below.

​
Step 3: Scenario Portfolio Analysis

The simplest way to analyze portfolio impact. Describe any scenario in plain English and the API generates a probability tree of outcomes with portfolio-level returns. 
curl -X POST "https://tilt.io/api/v1/backchannel/risk/scenario_portfolio_analysis" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_description": "China begins naval blockade of Taiwan, semiconductor supply chain completely severed",
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "search_for_context": true,
    "include_security_details": true
  }'

​
Key parameters

ParameterTypeDefaultDescription
scenario_descriptionstring—Plain English description of the scenario to analyze.
portfolio_weightsobject—Map of tilt_asset_id → weight.
as_of_datestringtodayDate for the analysis (YYYY-MM-DD).
search_for_contextbooleantrueSearch for relevant background articles to improve scenario quality.
include_security_detailsbooleantrueInclude per-security breakdown in each leaf scenario.
aggregate_scenariosbooleanfalseCollapse the scenario tree into summary stats.

​
Response structure

The response includes an AI-generated scenario tree, leaf-level portfolio impacts, and a probability-weighted expected return: 
{
  "success": true,
  "scenario_description": "China begins naval blockade of Taiwan...",
  "as_of_date": "2026-03-10",
  "expected_portfolio_return_pct": -0.0607,
  "portfolio_summary": {
    "num_scenarios": 3,
    "num_leaf_scenarios": 8,
    "num_securities": 3
  },
  "scenario_tree": [
    {
      "probability": 40,
      "title": "Full blockade with military escalation",
      "description": "...",
      "macro_shocks": [...],
      "sub_scenarios": [...]
    }
  ],
  "leaf_scenarios": [
    {
      "path": ["Full blockade with military escalation", "US military intervention"],
      "joint_probability_pct": 16,
      "portfolio_expected_return_pct": -0.12,
      "security_details": [
        {
          "tilt_id": "MH33D6-R",
          "ticker": "AAPL",
          "company_name": "Apple, Inc.",
          "weight": 0.40,
          "expected_return_pct": -0.1559,
          "contribution_to_portfolio_pct": -0.0624
        }
      ]
    }
  ],
  "context_articles": ["Taiwan Export Growth Lost Momentum in February", "..."],
  "generated_at": "2026-03-10T14:30:00"
}
Key fields:
FieldDescription
expected_portfolio_return_pctProbability-weighted expected portfolio return across all leaf scenarios. Decimal form (0.01 = 1%).
portfolio_summaryCounts of scenarios, leaf scenarios, and securities analyzed.
scenario_treeThe full probability tree with nested sub-scenarios and macro shocks.
leaf_scenariosFlattened leaf nodes with joint probabilities and per-security details.
context_articlesHeadlines of articles used as background context (when search_for_context is true).
This endpoint uses AI to generate scenarios, so responses take 10–30 seconds. For instant results on pre-computed news scenarios, use the Search Scenarios endpoint below instead.
View API Reference →

​
Step 4: Search News Scenarios with Portfolio Exposure

Search for curated, pre-computed news scenarios and see how each one affects your portfolio. This is instant (no AI generation) and useful for browsing recent events. 
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"weight": 1, "query": "tariffs trade war"}],
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "aggregate_scenarios": true,
    "limit": 5
  }'

​
Key parameters

ParameterTypeDefaultDescription
queriesarray—Weighted search queries. Each has query (string) and weight (0–1).
portfolio_weightsobjectnullMap of tilt_asset_id → weight. When provided, each result includes a portfolio_exposure field.
aggregate_scenariosbooleanfalseWhen true, collapses the scenario tree into probability-weighted summary stats.
order_by_exposurebooleanfalseWhen true, sorts results by portfolio impact instead of relevance.
limitinteger10Number of results (1–100).
min_importanceintegernullFilter to scenarios with importance rating >= this value (1–10).

​
Response structure

The response wraps results in articles. Each article is a news scenario with timeline, probability tree, and (when portfolio_weights is provided) portfolio exposure: 
{
  "success": true,
  "articles_found": 5,
  "articles": [
    {
      "point_id": "3fb7a574-c0d7-53b0-96cc-b98a2882f1c7",
      "headline": "Nvidia Invests in Mira Murati's Thinking Machines Lab",
      "date": "2026-03-10T00:00:00",
      "tilt_source": "WSJ",
      "importance_rating": 6,
      "timeline": [
        {"date": "2024-09-28", "summary": "OpenAI CTO Mira Murati resigns amid tensions"},
        {"date": "2026-01-26", "summary": "Nvidia invests $2B in CoreWeave for 5GW AI-factories"}
      ],
      "scenarios": [
        {
          "probability": 34,
          "title": "Compute-fueled breakout",
          "description": "Thinking Machines converts Nvidia's investment into a fast ramp of training and inference capacity...",
          "macro_shocks": [
            {"indicator": "rbics_55", "impact": 0.012},
            {"indicator": "VIXCLS", "impact": -0.6},
            {"indicator": "company_K7TPSX-R", "impact": 0.09}
          ],
          "sub_scenarios": [
            {
              "probability": 60,
              "title": "Frontier model debut",
              "description": "...",
              "macro_shocks": [...]
            }
          ]
        }
      ],
      "portfolio_exposure": {
        "expected_return_pct": 0.0049,
        "mad_pct": 0.0441,
        "num_leaf_scenarios": 8,
        "scenario_level_details": [
          {
            "title": "Compute-fueled breakout",
            "probability_pct": 34,
            "portfolio_return_mean_pct": 0.0693,
            "portfolio_return_std_pct": 0.0309,
            "sub_scenario_count": 2
          }
        ]
      }
    }
  ]
}
Key fields in portfolio_exposure:
FieldDescription
expected_return_pctProbability-weighted expected portfolio return across all leaf scenarios. Decimal form (0.01 = 1%).
mad_pctMean absolute deviation of returns across leaf scenarios — a measure of outcome uncertainty.
num_leaf_scenariosNumber of leaf nodes in the scenario tree used for the calculation.
scenario_level_detailsPer-scenario breakdown with mean return, standard deviation, and sub-scenario count.
View API Reference →

​
Step 5: Get a Single Scenario with Portfolio Exposure

Once you have a point_id from search results, fetch its full detail with portfolio exposure: 
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/3fb7a574-c0d7-53b0-96cc-b98a2882f1c7" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "include_content": true,
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "aggregate_scenarios": false
  }'
When aggregate_scenarios is false, the response includes leaf_details and scenario_level_details within portfolio_exposure, giving you the full probability tree with per-leaf portfolio returns. View API Reference →

​
Step 6: Macro Factor Analysis

​
Get Macro Sensitivities

Understand which macro factors your portfolio is most exposed to: 
curl -X POST "https://tilt.io/api/v1/backchannel/risk/sensitivities" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "limit": 5
  }'
The response ranks macro factors by portfolio-level exposure, showing which factors would move your portfolio the most: 
{
  "success": true,
  "type": "portfolio",
  "valid_securities": 3,
  "total_weight": 1,
  "portfolio_macro_exposures": [
    {
      "macro_factor": "macro_DTWEXBGS",
      "description": "US Dollar Index (Trade Weighted)",
      "portfolio_exposure": -2.1324,
      "top_contributors": [
        {"tilt_id": "MH33D6-R", "weight": 0.4, "sensitivity": -2.0164, "contribution": -0.8065},
        {"tilt_id": "K7TPSX-R", "weight": 0.25, "sensitivity": -3.1648, "contribution": -0.7912},
        {"tilt_id": "P8R3C2-R", "weight": 0.35, "sensitivity": -1.5277, "contribution": -0.5347}
      ]
    }
  ]
}
View API Reference →

​
Run a Macro Scenario

Use the sensitivities output to stress-test with specific macro shocks. The shocks object maps factor identifiers to shock magnitudes in standard deviations.
The sensitivities endpoint returns factor names with a macro_ prefix (e.g. macro_DTWEXBGS). When passing shocks to the scenario endpoint, drop the prefix — use the raw identifier (e.g. DTWEXBGS).
curl -X POST "https://tilt.io/api/v1/backchannel/risk/scenario" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "shocks": {
      "DTWEXBGS": 0.5
    },
    "include_security_details": true
  }'
The response shows the expected portfolio return and per-security breakdown: 
{
  "success": true,
  "portfolio_expected_return_pct": -1.0662,
  "shocks_applied": {
    "DTWEXBGS": 0.5
  },
  "factor_summary": [
    {
      "factor": "DTWEXBGS",
      "type": "fred",
      "description": "US Dollar Index (Trade Weighted)",
      "shock": 0.5,
      "portfolio_impact_pct": -1.0662
    }
  ],
  "security_details": [
    {
      "tilt_id": "MH33D6-R",
      "ticker": "AAPL",
      "company_name": "Apple, Inc.",
      "weight": 0.40,
      "expected_return_pct": -0.8066,
      "contribution_to_portfolio_pct": -0.3226,
      "factor_contributions": {
        "DTWEXBGS": -0.8066
      }
    }
  ]
}
View API Reference →

​
Putting It Together

A typical integration flow:
  1. Resolve tickers once and cache the tilt_asset_id mapping.
  2. Run scenario portfolio analysis with a plain English description to quickly assess portfolio impact for any hypothetical event. This is the easiest starting point.
  3. Search news scenarios with portfolio_weights to find real-world events that matter to the portfolio. Use order_by_exposure: true to surface the highest-impact stories first.
  4. Fetch individual scenarios with portfolio_weights for detailed drill-down with leaf-level probability breakdowns.
  5. Get macro sensitivities to understand the portfolio’s factor exposures.
  6. Run macro scenarios to stress-test against specific factor shocks (e.g., “what if the US Dollar Index rises 0.5 standard deviations?”).
Scenario Portfolio Analysis (Step 3) generates scenarios on-the-fly using AI, so it takes 10–30 seconds but works for any scenario you can describe. Search Scenarios (Step 4) returns pre-computed news scenarios instantly. Use scenario portfolio analysis for hypothetical what-if questions, and search scenarios for browsing recent real-world events.