Skip to main content

​
1. Get your API key

Sign up at gildea.ai to get your API key. Keys are prefixed with gld_.

​
2. List signals

Filter by entity, theme, or q — or omit all filters to get the most recent signals. 
from gildea_sdk import Gildea

client = Gildea()  # reads GILDEA_API_KEY from env
signals = client.signals.list(entity="NVIDIA", limit=3)
for signal in signals["data"]:
    print(f"{signal['title']} — {signal['verified_text_unit_count']} verified units")
Response — lightweight signal cards with metadata: 
{
  "data": [
    {
      "signal_id": "sig_01JABCDEF123456789",
      "title": "NVIDIA H200 Shipments Surge as Supply Eases",
      "content_type": "analysis",
      "published_at": "2026-01-15T10:00:00Z",
      "decomposition_text": "NVIDIA's H200 shipments increased significantly in Q4...",
      "tags": {
        "value_chain": ["Infrastructure"],
        "market_force": ["Competitive Dynamics"]
      },
      "entities": [
        {"entity_id": "org:/nvidia", "name": "NVIDIA", "type": "Organization"}
      ],
      "verified_text_unit_count": 12
    }
  ],
  "has_more": true,
  "next_cursor": "eyJwdWJsaXNoZWRfYXQiOi..."
}

​
3. Get the full decomposition

This is Gildea’s core value — the complete verified reasoning structure of a signal: 
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/signals/sig_01JABCDEF123456789?include=evidence"
Response — expert analysis signals have thesis + argument + claims, each verified: 
{
  "signal_id": "sig_01JABCDEF123456789",
  "content_type": "analysis",
  "decomposition": {
    "thesis": {
      "text": "NVIDIA's H200 shipments increased significantly in Q4...",
      "sentences": [
        {
          "unit": {
            "unit_type": "thesis_sentence",
            "text": "NVIDIA's H200 shipments increased significantly in Q4."
          },
          "verification": {
            "final_verdict": "pass",
            "scoring_mode": "regression",
            "primary_score": 0.8912
          },
          "evidence": {
            "parts": [
              {
                "part_index": 0,
                "preview_prefix": "According to supply chain data, NVIDIA shipped over 400,000 H200 units in Q4, a 40% increase from...",
                "preview_truncated": true,
                "full_part_char_length": 342
              }
            ],
            "combined_full_char_length": 342
          }
        }
      ]
    },
    "arguments": [
      {
        "sentences": [{ "..." : "..." }],
        "claims": [
          {
            "unit": {
              "unit_type": "analysis_claim",
              "text": "NVIDIA increased H200 shipments by 40% quarter-over-quarter."
            },
            "verification": {
              "final_verdict": "pass",
              "scoring_mode": "nli",
              "primary_score": 0.7421
            }
          }
        ]
      }
    ]
  }
}
Event signals have a summary + claims structure instead of thesis + arguments + claims. See Signals for details.

​
4. Explore entities and themes

from gildea_sdk import Gildea

client = Gildea()

# Rising entities with statistical significance
rising = client.entities.list(direction="Rising", confidence="Significant", sort="trend", limit=5)

# Entity profile
nvidia = client.entities.get("NVIDIA")

# Themes
themes = client.themes.list(axis="value_chain")

# Semantic search
results = client.search("GPU supply constraints", limit=5)

​
Next steps

Python SDK

Install the official client library

Signals

Understand signal decomposition

Themes

Value chain and market force themes

Authentication

API key setup and tiers

MCP Server

Connect via MCP