Quickstart

1. Get your API key

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_preview": {
        "snippets": [
          { "text": "The private and public demand for AI is creating…", "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_preview": { "snippets": [{ "text": "Each permissioning process runs on different…", "truncated": true }] }
    },
    {
      "id": "7ec0c9d34de97766e5d04c786c3f112890c49f36",
      "role": "claim",
      "text": "By early 2026, 777 hyperscale data center projects totaling 190 GW of capacity have been announced.",
      "evidence_preview": { "snippets": [{ "text": "AI is the most power-intensive workload in…", "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

Get started

Integrations

API

Recipes

Changelog

1. Get your API key

2. List signals

3. Get the full verified units

4. Explore entities and themes

Next steps

Python SDK

Signals

Themes

Authentication

MCP Server

​1. Get your API key

​2. List signals

​3. Get the full verified units

​4. Explore entities and themes

​Next steps

Python SDK

Signals

Themes

Authentication

MCP Server

1. Get your API key

2. List signals

3. Get the full verified units

4. Explore entities and themes

Next steps