Workflow Tutorial

A complete, step-by-step tutorial for building your first company search workflow.

Overview

In this tutorial, you’ll learn how to:

  1. Start a company search workflow
  2. Review and modify extracted criteria
  3. Continue the workflow with your criteria
  4. Monitor progress in real-time
  5. Retrieve and use the results

Time to complete: ~10 minutes

Prerequisites

  • API credentials and service ID
  • Basic knowledge of REST APIs
  • cURL or a REST client (Postman, Insomnia, etc.)

Step 1: Define Your Search

Let’s search for AI startups in San Francisco that have raised Series A funding.

Our search criteria:

  • Industry: Artificial Intelligence
  • Location: San Francisco
  • Funding Stage: Series A

Step 2: Start the Workflow

Make a POST request to start the workflow:

import requests
 
response = requests.post(
    'https://chordian-core.chordian.ai/api/workflow/start',
    json={
        'prompt': 'Find AI startups in San Francisco that have raised Series A funding',
        'serviceId': 'your-service-id',
        'total_target': 25
    }
)
 
data = response.json()
print(f"Thread ID: {data['thread_id']}")

Response

The API will return a streaming response. Save the thread_id:

{
  "thread_id": "wf_abc123def456",
  "status": "processing",
  "message": "Workflow started successfully"
}

Step 3: Check Extracted Criteria

Wait a few seconds, then check the workflow status:

curl https://chordian-core.chordian.ai/api/workflow/status/wf_abc123def456

Response

{
  "thread_id": "wf_abc123def456",
  "current_step": "criteria_extraction",
  "criteria": [
    {
      "name": "Industry",
      "value": "Artificial Intelligence",
      "column_name": "industry",
      "description": "AI and machine learning companies"
    },
    {
      "name": "Location",
      "value": "San Francisco",
      "column_name": "location",
      "description": "Company headquarters location"
    },
    {
      "name": "Funding Stage",
      "value": "Series A",
      "column_name": "funding_stage",
      "description": "Companies that have raised Series A"
    }
  ],
  "total_target": 25
}

? Info: Review the criteria carefully! The AI extracts criteria from your prompt. You can modify them before continuing.

Step 4: Continue the Workflow

If the criteria look good, continue the workflow:

import requests
 
response = requests.post(
    'https://chordian-core.chordian.ai/api/workflow/continue',
    json={
        'thread_id': 'wf_abc123def456',
        'total_target': 25,
        'current_criteria': [
            {
                'name': 'Industry',
                'value': 'Artificial Intelligence',
                'column_name': 'industry'
            },
            {
                'name': 'Location',
                'value': 'San Francisco',
                'column_name': 'location'
            },
            {
                'name': 'Funding Stage',
                'value': 'Series A',
                'column_name': 'funding_stage'
            }
        ]
    }
)

Step 5: Monitor Progress

Poll the status endpoint every 5 seconds to monitor progress:

# Check status
curl https://chordian-core.chordian.ai/api/workflow/status/wf_abc123def456

Progress Indicators

Watch the current_step field:

  • criteria_extraction → Extracting criteria
  • data_collection → Finding companies
  • enrichment → Adding details
  • completed → Done!

Step 6: Get Results

When current_step is completed, retrieve the results from table_structure:

{
  "thread_id": "wf_abc123def456",
  "current_step": "completed",
  "table_structure": {
    "columns": [
      { "id": "company_name", "header": "Company Name", "type": "fixed" },
      { "id": "website", "header": "Website", "type": "fixed" },
      { "id": "industry", "header": "Industry", "type": "dynamic" },
      { "id": "location", "header": "Location", "type": "dynamic" },
      { "id": "funding_stage", "header": "Funding Stage", "type": "dynamic" }
    ],
    "rows": [
      {
        "id": "row_1",
        "cells": {
          "company_name": { "value": "AI Innovations Inc", "status": "completed" },
          "website": { "value": "https://aiinnovations.com", "status": "completed" },
          "industry": { "value": "Artificial Intelligence", "status": "completed" },
          "location": { "value": "San Francisco, CA", "status": "completed" },
          "funding_stage": { "value": "Series A", "status": "completed" }
        }
      }
      // ... more rows
    ],
    "current_count": 25,
    "total_target": 25
  }
}

Advanced: Adding Custom Criteria

You can add additional criteria when continuing:

{
  "thread_id": "wf_abc123def456",
  "total_target": 25,
  "current_criteria": [...],
  "additional_criteria": [
    {
      "name": "Employee Count",
      "value": "50-200",
      "column_name": "employee_count",
      "description": "Number of employees"
    }
  ]
}

Complete Example (JavaScript)

Here’s a complete workflow implementation:

const API_BASE = 'https://chordian-core.chordian.ai';
const SERVICE_ID = 'your-service-id';
 
async function runWorkflow() {
  // 1. Start workflow
  const startRes = await fetch(`${API_BASE}/api/workflow/start`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt: 'Find AI startups in San Francisco with Series A funding',
      serviceId: SERVICE_ID,
      total_target: 25
    })
  });
  
  const { thread_id } = await startRes.json();
  console.log('Started:', thread_id);
  
  // 2. Wait for criteria extraction
  await sleep(3000);
  
  // 3. Get criteria
  const statusRes = await fetch(`${API_BASE}/api/workflow/status/${thread_id}`);
  const status = await statusRes.json();
  console.log('Criteria:', status.criteria);
  
  // 4. Continue workflow
  await fetch(`${API_BASE}/api/workflow/continue`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      thread_id,
      total_target: 25,
      current_criteria: status.criteria
    })
  });
  
  // 5. Poll for completion
  let completed = false;
  while (!completed) {
    await sleep(5000);
    const checkRes = await fetch(`${API_BASE}/api/workflow/status/${thread_id}`);
    const check = await checkRes.json();
    
    console.log(`Step: ${check.current_step}, Count: ${check.table_structure?.current_count || 0}`);
    
    if (check.current_step === 'completed') {
      completed = true;
      console.log('Results:', check.table_structure);
    }
  }
}
 
function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
 
runWorkflow();

Next Steps