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 keyword, or omit all filters to get the most recent signals. 
from gildea import Gildea

client = Gildea()  # reads GILDEA_API_KEY from env
signals = client.signals.list(entity="NVIDIA", limit=3)
for signal in signals["signals"]:
    print(f"{signal['title']}: {signal['verified_unit_count']} verified units")

curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/signals?entity=NVIDIA&limit=3"

import requests

resp = requests.get(
    "https://api.gildea.ai/v1/signals",
    headers={"X-API-Key": "gld_your_key"},
    params={"entity": "NVIDIA", "limit": 3},
)
for signal in resp.json()["signals"]:
    print(f"{signal['title']}: {signal['verified_unit_count']} verified units")

const resp = await fetch(
  "https://api.gildea.ai/v1/signals?entity=NVIDIA&limit=3",
  { headers: { "X-API-Key": "gld_your_key" } }
);
const { signals } = await resp.json();
signals.forEach(s => console.log(`${s.title}: ${s.verified_unit_count} units`));
Response: lightweight signal cards with metadata: 
{
  "signals": [
    {
      "signal_id": "0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
      "title": "NVIDIA H200 Shipments Surge as Supply Eases",
      "url": "https://reuters.com/article",
      "published_at": "2026-01-15T10:00:00Z",
      "content_type": "analysis",
      "domain": "reuters.com",
      "verified_unit_count": 12,
      "thesis": "NVIDIA's H200 shipments increased significantly in Q4...",
      "themes": {
        "value_chain": ["Infrastructure"],
        "market_force": ["Competitive Dynamics"]
      },
      "entities": [
        {"entity_id": "gld:/a1b2c3d4e5f6", "name": "NVIDIA", "type": "organization"}
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "eyJwdWJsaXNoZWRfYXQiOi..."
}
Event signals carry a flat synopsis field here instead of thesis.

​
3. Get the full verified units

This is Gildea’s core value: the complete verified breakdown of a signal as a flat list of units. Pass any signal_id from your Step 2 response; the one below is a live example: 
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/signals/d67e4e83d32e1db358c8e03d14f3877c6e35a0d6"
Response: a flat units[], each carrying a role (thesis / synopsis / argument / claim) and its cited evidence by default: 
{
  "signal_id": "d67e4e83d32e1db358c8e03d14f3877c6e35a0d6",
  "content_type": "analysis",
  "domain": "bvp.com",
  "verified_unit_count": 25,
  "themes": { "value_chain": ["Infrastructure"], "market_force": ["Capital & Investment"] },
  "entities": [
    { "entity_id": "gld:/28193456262a", "name": "NVIDIA", "type": "organization" },
    { "entity_id": "gld:/e02d80668c57", "name": "Digital Realty Trust Inc.", "type": "organization" }
  ],
  "units": [
    {
      "id": "e8edd00cef2b66398b78cd4413619272fb4b7362",
      "role": "thesis",
      "text": "The private and public demand for AI is creating one of the largest infrastructure investment cycles, offering a massive opening for startups.",
      "evidence": {
        "snippets": [
          { "text": "The private and public demand for AI is creating one of the largest infrastructure investment cycles…", "truncated": true }
        ]
      }
    },
    {
      "id": "35019e4be886b1e4dc3159a6afb1ed7a8b2ef0d7",
      "role": "argument",
      "text": "Obtaining permission to operate data centers involves diverse local regulations and timelines, with 16 data center developments delayed or denied between March 2024 and 2025 due to permitting restrictions.",
      "argument_id": "a1",
      "evidence": { "snippets": [{ "text": "Each permissioning process runs on different timelines and varies at the local jurisdiction. Between…", "truncated": true }] }
    },
    {
      "id": "7ec0c9d34de97766e5d04c786c3f112890c49f36",
      "role": "claim",
      "text": "By early 2026, 777 hyperscale data center projects totaling 190 GW of capacity have been announced.",
      "evidence": { "snippets": [{ "text": "AI is the most power-intensive workload in computing history. As of early 2026, 190 GW of hyperscale…", "truncated": true }] }
    }
  ]
}
Reconstruct prose by role: concatenate the thesis (or synopsis) units for the central statement, and group argument units by argument_id. Event signals use synopsis instead of thesis and have no argument units. See Signals for details.

​
4. Explore entities and themes

from gildea 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)

# Rising entities with statistical significance
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/entities?direction=Rising&confidence=Significant&sort=trend&limit=5"

# Entity profile
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/entities/NVIDIA"

# Themes
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/themes?axis=value_chain"

# Semantic search
curl -H "X-API-Key: gld_your_key" \
  "https://api.gildea.ai/v1/search?q=GPU%20supply%20constraints&limit=5"

import requests

headers = {"X-API-Key": "gld_your_key"}

# Rising entities with statistical significance
rising = requests.get(
    "https://api.gildea.ai/v1/entities",
    headers=headers,
    params={"direction": "Rising", "confidence": "Significant", "sort": "trend", "limit": 5},
).json()

# Entity profile
nvidia = requests.get(
    "https://api.gildea.ai/v1/entities/NVIDIA",
    headers=headers,
).json()

# Themes
themes = requests.get(
    "https://api.gildea.ai/v1/themes",
    headers=headers, params={"axis": "value_chain"},
).json()

# Semantic search
results = requests.get(
    "https://api.gildea.ai/v1/search",
    headers=headers, params={"q": "GPU supply constraints", "limit": 5},
).json()

const headers = { "X-API-Key": "gld_your_key" };

// Rising entities with statistical significance
const rising = await fetch(
  "https://api.gildea.ai/v1/entities?direction=Rising&confidence=Significant&sort=trend&limit=5",
  { headers }
).then(r => r.json());

// Entity profile
const nvidia = await fetch(
  "https://api.gildea.ai/v1/entities/NVIDIA",
  { headers }
).then(r => r.json());

// Themes
const themes = await fetch(
  "https://api.gildea.ai/v1/themes?axis=value_chain",
  { headers }
).then(r => r.json());

// Semantic search
const results = await fetch(
  "https://api.gildea.ai/v1/search?q=GPU%20supply%20constraints&limit=5",
  { headers }
).then(r => r.json());

​
Next steps

Python SDK

Install the official client library

Signals

Understand the verified-unit model

Themes

Value chain and market force themes

Authentication

API key setup and tiers

MCP Server

Connect via MCP