Topic Monitoring

Set up continuous monitoring for specific topics, keywords, and market trends relevant to your business. Topic monitoring allows you to detect signals across companies matching criteria you define—without needing to create a list of specific companies first.

Prerequisites

Before starting, ensure you have:

A Linkt account with API access
Your API key (see Authentication)
Understanding of Signals

Understanding Monitoring Mode

For topic monitoring, create an ICP with mode: "monitoring". This tells Linkt to focus on detecting signals rather than discovering new entities.

ICP Modes

See ICPs for a complete explanation of discovery vs monitoring modes.

Step 1: Create a Monitoring ICP

Create an ICP with mode: "monitoring" that defines the types of companies to monitor.

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI SaaS Companies",
    "description": "Monitor AI-focused SaaS companies for signals",
    "mode": "monitoring",
    "entity_targets": [
      {
        "entity_type": "company",
        "description": "AI/ML-focused SaaS companies with Series A+ funding",
        "root": true
      }
    ]
  }'

Response:

{
  "id": "507f1f77bcf86cd799439001",
  "name": "AI SaaS Companies",
  "mode": "monitoring",
  "entity_targets": [...],
  "created_at": "2025-01-06T10:00:00Z"
}

Monitoring vs Discovery

Set mode: "monitoring" for signal workflows. The ICP-level description is for display purposes—the entity target description defines the criteria the AI uses for monitoring.

Step 2: Configure Signal Types

Define which types of signals you want to detect. Each signal type requires:

type — Signal type enum value
display — Human-readable name
description — Detailed description of what to monitor

Available Signal Types

Type	Description
`funding`	Investment rounds, grants, capital raises
`leadership_change`	CEO, executive, board changes
`layoff`	Workforce reduction, restructuring
`product_launch`	New products, features, major updates
`partnership`	Strategic alliances, integrations
`acquisition`	M&A activity
`expansion`	Geographic expansion, new markets
`award`	Industry recognition, certifications
`hiring_surge`	Unusual hiring activity
`rfp`	RFP issuance, vendor evaluations

See Signals for the complete list of 17 signal types.

Step 3: Create a Signal Task

Create a signal task with the signal-topic configuration. This defines:

What companies to monitor (topic_criteria)
What signals to detect (signal_types)
How often to check (monitoring_frequency)

curl -X POST "https://api.linkt.ai/v1/task" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI SaaS Signal Monitor",
    "description": "Monitor for funding and product signals in AI SaaS space",
    "flow_name": "signal",
    "deployment_name": "main",
    "icp_id": "507f1f77bcf86cd799439001",
    "task_config": {
      "version": "v2.0",
      "config_type": "signal-topic",
      "entity_type": "company",
      "topic_criteria": "AI/ML-focused SaaS companies with Series A+ funding in North America",
      "signal_types": [
        {
          "type": "funding",
          "display": "Funding Announcements",
          "description": "Series A through Series D funding rounds"
        },
        {
          "type": "product_launch",
          "display": "Product Updates",
          "description": "New AI features or major product releases"
        },
        {
          "type": "leadership_change",
          "display": "Leadership Changes",
          "description": "New CTO, VP Engineering, or C-suite changes"
        }
      ],
      "monitoring_frequency": "daily",
      "industry_filters": ["AI/ML", "SaaS"],
      "geographic_filters": ["North America"],
      "webhook_url": "https://your-server.com/webhooks/linkt"
    }
  }'

Response:

{
  "id": "507f1f77bcf86cd799439002",
  "name": "AI SaaS Signal Monitor",
  "flow_name": "signal",
  "task_config": {
    "version": "v2.0",
    "config_type": "signal-topic",
    "topic_criteria": "AI/ML-focused SaaS companies...",
    "signal_types": [...],
    "monitoring_frequency": "daily"
  },
  "created_at": "2025-01-06T10:01:00Z"
}

Task Configuration Fields

Field	Required	Description
`config_type`	Yes	Must be `signal-topic`
`version`	Yes	Config version (use `v2.0`)
`entity_type`	Yes	Entity type: `company` or `person`
`topic_criteria`	Yes	Natural language description of entities to monitor
`signal_types`	Yes	Array of signal type configurations
`monitoring_frequency`	No	`daily`, `weekly` (default), or `monthly`
`industry_filters`	No	Industries to focus on
`geographic_filters`	No	Geographic regions to focus on
`company_size_filters`	No	Employee count ranges
`webhook_url`	No	HTTPS URL to receive completion notifications (see Webhooks)

Step 4: Execute Monitoring

Execute the task to start signal detection.

curl -X POST "https://api.linkt.ai/v1/task/507f1f77bcf86cd799439002/execute" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "icp_id": "507f1f77bcf86cd799439001"
  }'

Response:

{
  "run_id": "507f1f77bcf86cd799439003",
  "flow_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SCHEDULED"
}

The run will progress through states: SCHEDULED → PENDING → RUNNING → COMPLETED. Poll the run endpoint until it reaches a terminal state.

Monitoring Execution

See Execution for polling patterns, status handling, and error recovery.

Step 5: Retrieve Signals

Once monitoring completes, retrieve the detected signals.

curl -X GET "https://api.linkt.ai/v1/signal?icp_id=507f1f77bcf86cd799439001&days=7" \
  -H "x-api-key: your-api-key"

Response:

{
  "signals": [
    {
      "id": "507f1f77bcf86cd799439010",
      "icp_id": "507f1f77bcf86cd799439001",
      "entity_ids": [],
      "summary": "TechCorp AI announced a $45M Series B round led by Sequoia Capital, bringing total funding to $60M.",
      "signal_type": "funding",
      "signal_display_name": "Funding Announcements",
      "strength": "HIGH",
      "references": ["https://techcrunch.com/techcorp-series-b"],
      "created_at": "2025-01-06T14:30:00Z"
    },
    {
      "id": "507f1f77bcf86cd799439011",
      "icp_id": "507f1f77bcf86cd799439001",
      "entity_ids": [],
      "summary": "DataML Inc launched a new AI-powered analytics platform targeting enterprise customers.",
      "signal_type": "product_launch",
      "signal_display_name": "Product Updates",
      "strength": "MEDIUM",
      "references": ["https://dataml.com/blog/new-platform"],
      "created_at": "2025-01-06T11:15:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20
}

Topic-Based Signals

With topic monitoring, entity_ids may be empty since signals are discovered based on topic criteria rather than pre-existing entities.

Filtering by Signal Type

Query signals by type to focus on specific events:

# Get only funding signals
curl -X GET "https://api.linkt.ai/v1/signal?icp_id={icp_id}&signal_type=funding" \
  -H "x-api-key: your-api-key"
 
# Get high-strength signals only
curl -X GET "https://api.linkt.ai/v1/signal?icp_id={icp_id}&strength=HIGH" \
  -H "x-api-key: your-api-key"
 
# Search for specific terms
curl -X GET "https://api.linkt.ai/v1/signal?icp_id={icp_id}&search_term=Series%20B" \
  -H "x-api-key: your-api-key"

Query Parameters

Parameter	Description
`icp_id`	Filter by ICP
`signal_type`	Filter by type (e.g., `funding`)
`strength`	Filter by strength: `LOW`, `MEDIUM`, `HIGH`
`search_term`	Search in summary text
`days`	Look back period (1-90, default 30)
`page`, `page_size`	Pagination

Building Alerts

Create an alerting system by polling for new signals periodically.

import requests
import time
from datetime import datetime, timedelta
 
API_KEY = "your-api-key"
ICP_ID = "507f1f77bcf86cd799439001"
 
def check_for_signals(since_hours=1):
    """Check for signals in the last N hours."""
    headers = {"x-api-key": API_KEY}
 
    response = requests.get(
        f"https://api.linkt.ai/v1/signal",
        headers=headers,
        params={
            "icp_id": ICP_ID,
            "days": 1,
            "strength": "HIGH",  # Only high-priority signals
            "page_size": 50
        }
    )
 
    signals = response.json()["signals"]
 
    # Filter to recent signals
    cutoff = datetime.utcnow() - timedelta(hours=since_hours)
    recent = [
        s for s in signals
        if datetime.fromisoformat(s["created_at"].replace("Z", "")) > cutoff
    ]
 
    return recent
 
def send_alert(signal):
    """Send alert for a signal (customize for your needs)."""
    print(f"[{signal['signal_type'].upper()}] {signal['summary']}")
    print(f"  Strength: {signal['strength']}")
    print(f"  Source: {signal['references'][0] if signal['references'] else 'N/A'}")
    print()
 
    # Add your notification logic here:
    # - Send Slack message
    # - Send email
    # - Post to webhook
    # - Update CRM
 
def run_alerting_loop(check_interval_minutes=60):
    """Run continuous alerting."""
    print("Starting signal alerting loop...")
 
    while True:
        try:
            signals = check_for_signals(since_hours=1)
 
            if signals:
                print(f"Found {len(signals)} new signals:")
                for signal in signals:
                    send_alert(signal)
            else:
                print("No new signals")
 
        except Exception as e:
            print(f"Error checking signals: {e}")
 
        time.sleep(check_interval_minutes * 60)
 
# Run the alerting loop
run_alerting_loop(check_interval_minutes=60)

Complete Example

Here's a complete workflow for topic monitoring:

import requests
import time
 
API_KEY = "your-api-key"
BASE_URL = "https://api.linkt.ai/v1"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
 
def setup_topic_monitoring(topic, signal_types):
    """Set up topic monitoring from scratch."""
 
    # Step 1: Create monitoring ICP
    print("Creating monitoring ICP...")
    icp_response = requests.post(
        f"{BASE_URL}/icp",
        headers=HEADERS,
        json={
            "name": f"Monitor: {topic}",
            "description": f"Signal monitoring for {topic}",
            "mode": "monitoring",
            "entity_targets": [{
                "entity_type": "company",
                "description": topic,
                "root": True
            }]
        }
    )
    icp_id = icp_response.json()["id"]
    print(f"  Created ICP: {icp_id}")
 
    # Step 2: Create signal task
    print("Creating signal task...")
    task_response = requests.post(
        f"{BASE_URL}/task",
        headers=HEADERS,
        json={
            "name": f"Signal Monitor: {topic}",
            "description": f"Monitor for signals on {topic}",
            "flow_name": "signal",
            "deployment_name": "main",
            "icp_id": icp_id,
            "task_config": {
                "version": "v2.0",
                "config_type": "signal-topic",
                "entity_type": "company",
                "topic_criteria": topic,
                "signal_types": signal_types,
                "monitoring_frequency": "daily"
            }
        }
    )
    task_id = task_response.json()["id"]
    print(f"  Created task: {task_id}")
 
    # Step 3: Execute
    print("Executing monitoring task...")
    run_response = requests.post(
        f"{BASE_URL}/task/{task_id}/execute",
        headers=HEADERS,
        json={"icp_id": icp_id}
    )
    run_id = run_response.json()["run_id"]
    print(f"  Started run: {run_id}")
 
    # Step 4: Wait for completion
    print("Waiting for completion...")
    while True:
        run = requests.get(
            f"{BASE_URL}/run/{run_id}",
            headers={"x-api-key": API_KEY}
        ).json()
 
        if run["status"] == "COMPLETED":
            break
        elif run["status"] in ["FAILED", "CANCELED", "CRASHED"]:
            raise Exception(f"Run failed: {run.get('error')}")
 
        time.sleep(10)  # Poll every 10 seconds
 
    # Step 5: Get signals
    print("Retrieving signals...")
    signals = requests.get(
        f"{BASE_URL}/signal",
        headers={"x-api-key": API_KEY},
        params={"icp_id": icp_id, "days": 7}
    ).json()
 
    print(f"Found {signals['total']} signals")
    return {
        "icp_id": icp_id,
        "task_id": task_id,
        "signals": signals["signals"]
    }
 
# Run topic monitoring
result = setup_topic_monitoring(
    topic="Series A+ funded fintech startups in the US",
    signal_types=[
        {
            "type": "funding",
            "display": "Funding Rounds",
            "description": "Any new funding announcements"
        },
        {
            "type": "product_launch",
            "display": "Product Launches",
            "description": "New product or feature announcements"
        },
        {
            "type": "partnership",
            "display": "Partnerships",
            "description": "Strategic partnerships or integrations"
        }
    ]
)
 
# Print results
for signal in result["signals"][:5]:
    print(f"\n[{signal['signal_type']}] {signal['summary'][:100]}...")

Other Signal Configuration Types

Besides topic monitoring, Linkt supports two other signal configurations:

Signal Sheet (`signal-sheet`)

Monitor entities from an existing sheet:

{
  "config_type": "signal-sheet",
  "source_icp_id": "507f1f77bcf86cd799439012",
  "entity_type": "company",
  "signal_types": [...],
  "monitoring_frequency": "weekly"
}

See Account Monitoring for details.

Signal CSV (`signal-csv`)

Monitor entities from an uploaded CSV. First upload your file using the Files API, then reference it by file_id:

{
  "config_type": "signal-csv",
  "file_id": "507f1f77bcf86cd799439001",
  "primary_column": "company_name",
  "entity_type": "company",
  "signal_types": [...],
  "monitoring_frequency": "daily",
  "webhook_url": "https://your-server.com/webhooks/linkt"
}

Webhook Notifications

Add webhook_url to receive HTTP POST notifications when workflows complete. See Webhooks for payload structure and integration examples.

Next Steps

Account Monitoring — Monitor specific companies from your sheets
Webhooks — Receive HTTP notifications when workflows complete
Signal Types Reference — All 17 signal types explained
Files Reference — File upload and management for signal-csv workflows
Signals Reference — Signal data structure
Execution — Understanding runs and monitoring

On this page