API Reference

Primary endpoint. Returns the full narrative hierarchy — global narratives, daily topics, articles, and LLM-generated insights — for one or more tickers. Max 10 tickers per request; see batching guidance below for larger portfolios.

Parameters

Batching for large portfolios

For portfolios exceeding 10 tickers, split into batches of 10 and merge results client-side. Each batch counts as one request against your rate limit quota.

import requests, time

API_KEY  = "nk_your_key"
BASE_URL = "https://aletaindex-narrative.com"

tickers = ["NVDA","TSLA","AAPL","MSFT","AMZN","GOOGL","META","AMD","NFLX","JPM","GS","V"]
batches = [tickers[i:i+10] for i in range(0, len(tickers), 10)]

results = []
for batch in batches:
    resp = requests.get(
        f"{BASE_URL}/v1/narratives/comprehensive",
        headers={"X-API-Key": API_KEY},
        params={"tickers": ",".join(batch), "from_date": "2026-05-04", "to_date": "2026-05-10"},
    ).json()
    results.extend(resp["results"])
    time.sleep(0.2)  # stay within rate limit

Response schema

{
  "query_summary": {
    "tickers": ["NVDA"],
    "timeframe": { "from_date": "2026-05-04", "to_date": "2026-05-10", "days": 7 },
    "requested_at": "2026-05-10T12:00:00+00:00"
  },
  "results": [
    {
      "ticker": "NVDA",
      "timeframe": { "from_date": "2026-05-04", "to_date": "2026-05-10" },
      "summary": {
        "global_narrative_count": 5,
        "daily_topic_count": 18,
        "article_count": 94,
        "source_count": 31
      },
      "insight": {
        "insights": {
          "summary": {
            "overall_sentiment_trend": "improving",
            "sentiment_trend_magnitude": 0.12,
            "overall_sentiment_score": 0.38,
            "overall_sentiment_label": "positive",
            "dominant_narrative": { "title": "...", "sentiment": "positive" },
            "key_metric": "Narrative momentum accelerating on Blackwell supply chain clarity"
          },
          "key_insights": [ "..." ],
          "anomalies": [ "..." ],
          "correlations": [ "..." ],
          "behavioral_patterns": {
            "narrative_correlations": [ "..." ],
            "price_correlations": [ "..." ]
          },
          "narrative_colors": { "1042": "#4F8EF7" }
        },
        "generated_at": "2026-05-10T06:00:00+00:00",
        "is_pre_generated": true,
        "actual_timeframe": { "from_date": "2026-05-04", "to_date": "2026-05-10", "days": 7 }
      },
      "global_narratives": [
        {
          "id": 1042,
          "title": "NVDA AI data center demand surge",
          "created_at": "2026-01-15T08:22:00",
          "last_updated_at": "2026-05-10T06:00:00",
          "metadata": { "daily_topic_count": 5, "article_count": 34 },
          "sentiment": { "avg_sentiment": 0.41, "sentiment_label": "positive" },
          "daily_topics": [
            {
              "id": 882,
              "title": "Blackwell GPU shipments beat estimates",
              "dominance_score": 0.78,
              "time": "2026-05-08",
              "article_count": 7,
              "avg_sentiment": 0.52,
              "sentiment_label": "positive",
              "articles": [
                {
                  "id": 9921,
                  "title": "NVIDIA Blackwell shipments top Wall Street forecasts",
                  "source": "Reuters",
                  "link": "https://reuters.com/...",
                  "published_at": "2026-05-08T14:23:00",
                  "representativeness_score": 0.94,
                  "ticker_relevance_score": 0.88,
                  "rank_in_topic": 1,
                  "is_duplicate": false,
                  "is_near_duplicate": false,
                  "sentiment": { "score": 0.47, "label": "positive" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Example

import requests
from datetime import date, timedelta

API_KEY  = "nk_your_key"
BASE_URL = "https://aletaindex-narrative.com"

to_date   = date.today()
from_date = to_date - timedelta(days=6)

resp = requests.get(
    f"{BASE_URL}/v1/narratives/comprehensive",
    headers={"X-API-Key": API_KEY},
    params={
        "tickers":                   "NVDA,TSLA",
        "from_date":                 from_date.isoformat(),
        "to_date":                   to_date.isoformat(),
        "article_sort_by":           "representativeness",
        "top_articles_per_daily_topic": 5,
    }
).json()

for result in resp["results"]:
    print(result["ticker"], "—", result["summary"]["global_narrative_count"], "narratives")
    for n in result["global_narratives"]:
        s = n["sentiment"]
        print(f"  [{s['sentiment_label']:8s}] {n['title']}")

curl "https://aletaindex-narrative.com/v1/narratives/comprehensive?tickers=NVDA,TSLA&from_date=2026-05-04&to_date=2026-05-10&top_articles_per_daily_topic=5" \
  -H "X-API-Key: nk_your_key"

Portfolio Narrative Risk Map. Given a list of holdings (ticker + weight), returns the dominant macro risk themes across your portfolio — each with exposure percentage, dominance score, and momentum trajectory (ESCALATING / STEADY / RECEDING). Themes are grouped using LLM-based semantic clustering, with cosine-similarity fallback. Analysis is based on the last 30 days of narrative data.

Request body

{
  "holdings": [
    {"ticker": "NVDA", "weight": 0.30},
    {"ticker": "AMD",  "weight": 0.20},
    {"ticker": "TSLA", "weight": 0.25},
    {"ticker": "AAPL", "weight": 0.25}
  ]
}

Response schema

{
  "top_risk": "AI Export Controls",
  "narratives": [
    {
      "theme": "AI Export Controls",
      "tickers": ["AMD", "NVDA"],
      "ticker_narratives": [
        {"ticker": "NVDA", "narrative": "NVDA Blackwell export license uncertainty"},
        {"ticker": "AMD",  "narrative": "AMD GPU export restrictions impact"}
      ],
      "narrative_ids": [1042, 1055],
      "exposure_pct": 50.0,
      "dominance": 0.74,
      "trajectory": "ESCALATING",
      "momentum_delta": 0.12
    }
  ],
  "uncovered_tickers": [],
  "credits_used": 4
}

Narratives are sorted by trajectory (ESCALATING first), then by exposure_pct descending. momentum_delta is the change in weighted dominance between the most recent 7-day window and the prior 7-day window. uncovered_tickers lists tickers for which no active narratives were found.

Credit cost

Credits deducted = number of unique tickers in the request. Returns 402 if balance is insufficient.

Example

import requests

API_KEY  = "nk_your_key"
BASE_URL = "https://aletaindex-narrative.com"

resp = requests.post(
    f"{BASE_URL}/v1/portfolio/narrative-risk",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={"holdings": [
        {"ticker": "NVDA", "weight": 0.30},
        {"ticker": "TSLA", "weight": 0.25},
        {"ticker": "AAPL", "weight": 0.25},
        {"ticker": "AMD",  "weight": 0.20},
    ]}
).json()

print("Top risk:", resp["top_risk"])
for theme in resp["narratives"]:
    print(f"  {theme['trajectory']:11s} {theme['theme']:30s} {theme['exposure_pct']}% exposure")

curl -X POST "https://aletaindex-narrative.com/v1/portfolio/narrative-risk" \
  -H "X-API-Key: nk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"holdings":[{"ticker":"NVDA","weight":0.3},{"ticker":"TSLA","weight":0.25},{"ticker":"AAPL","weight":0.25},{"ticker":"AMD","weight":0.2}]}'