Find Lists

Retrieve all custom lists (groupings) for your account. Project lists allow you to organize companies into meaningful groups such as industry verticals, investment stages, geographic regions, or custom categories.

Endpoint

GET https://api.kruncher.ai/api/integration/projectlists

Headers

Header	Required	Description
`Authorization`	Yes	Your API key (format: `YOUR_API_KEY`)
`Content-Type`	No	Optional `application/json`

Use Cases

When to Use This Endpoint

List Organization: See all available project groupings
Segmentation: Filter projects by custom categories
Portfolio Management: Organize by stage, industry, or geography
Team Workflows: Group projects for different team responsibilities
Reporting: Create reports by project list
Integration: Sync project lists with external systems

Code Examples

JavaScript/TypeScript

Basic

CODE

const API_KEY = "YOUR_API_KEY_HERE";
 
const response = await fetch("https://api.kruncher.ai/api/integration/projectlists", {
  headers: {
    "Authorization": `${API_KEY}`,
    "Content-Type": "application/json"
  }
});
 
const result = await response.json();
 
console.log(`Total lists: ${result.length}`);
result.forEach(list => {
  console.log(`- ${list.name} (${list.id})`);
  if (list.description) {
    console.log(`  Description: ${list.description}`);
  }
});

Result: Retrieves all project lists for your organization.

With Filtering

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
async function getProjectLists() {
  const response = await fetch(`${BASE_URL}/integration/projectlists`, {
    headers: {
      "Authorization": `${API_KEY}`,
      "Content-Type": "application/json"
    }
  });
 
  if (!response.ok) {
    throw new Error(`Failed to fetch lists: ${response.statusText}`);
  }
 
  return await response.json();
}
 
function filterListsByName(lists, searchTerm) {
  return lists.filter(list =>
    list.name.toLowerCase().includes(searchTerm.toLowerCase())
  );
}
 
function getListById(lists, id) {
  return lists.find(list => list.id === id) || null;
}
 
function groupListsByCategory(lists, categoryField = 'category') {
  return lists.reduce((grouped, list) => {
    const category = list[categoryField] || 'Uncategorized';
    if (!grouped[category]) {
      grouped[category] = [];
    }
    grouped[category].push(list);
    return grouped;
  }, {});
}
 
// Usage
const lists = await getProjectLists();
console.log(`Total lists: ${lists.length}`);
 
// Filter lists
const technologyLists = filterListsByName(lists, "technology");
console.log(`Technology lists: ${technologyLists.length}`);
 
// Get specific list
const myList = getListById(lists, "list_123");
if (myList) {
  console.log(`Found list: ${myList.name}`);
}
 
// Group lists
const grouped = groupListsByCategory(lists);
Object.entries(grouped).forEach(([category, categoryLists]) => {
  console.log(`${category}: ${categoryLists.length} lists`);
});

Result: Retrieves, filters, and organizes project lists.

Advanced

CODE

const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api";
 
class ProjectListManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = BASE_URL;
    this.cache = null;
    this.lastFetch = null;
    this.cacheDuration = 300000; // 5 minutes
  }
 
  async fetchLists(forceRefresh = false) {
    const now = Date.now();
 
    if (!forceRefresh && this.cache && (now - this.lastFetch < this.cacheDuration)) {
      return this.cache;
    }
 
    const response = await fetch(`${this.baseURL}/integration/projectlists`, {
      headers: {
        "Authorization": `${this.apiKey}`,
        "Content-Type": "application/json"
      }
    });
 
    if (!response.ok) {
      throw new Error(`Failed to fetch lists: ${response.statusText}`);
    }
 
    this.cache = await response.json();
    this.lastFetch = now;
 
    return this.cache;
  }
 
  async getListById(id) {
    const lists = await this.fetchLists();
    return lists.find(list => list.id === id) || null;
  }
 
  async getListByName(name) {
    const lists = await this.fetchLists();
    return lists.find(list => list.name === name) || null;
  }
 
  async findListsByPattern(pattern) {
    const lists = await this.fetchLists();
    const regex = new RegExp(pattern, 'i');
    return lists.filter(list => regex.test(list.name) || regex.test(list.description || ''));
  }
 
  async getAllLists() {
    return await this.fetchLists();
  }
 
  async getListCount() {
    const lists = await this.fetchLists();
    return lists.length;
  }
 
  async getListsByCategory(categoryField = 'category') {
    const lists = await this.fetchLists();
    
    const grouped = {};
    lists.forEach(list => {
      const category = list[categoryField] || 'Uncategorized';
      if (!grouped[category]) {
        grouped[category] = [];
      }
      grouped[category].push(list);
    });
    
    return grouped;
  }
 
  async getListsByOwner(owner) {
    const lists = await this.fetchLists();
    return lists.filter(list => list.owner === owner || list.createdBy === owner);
  }
 
  async searchLists(query) {
    const lists = await this.fetchLists();
    const lowerQuery = query.toLowerCase();
    
    return lists.filter(list =>
      list.name.toLowerCase().includes(lowerQuery) ||
      (list.description && list.description.toLowerCase().includes(lowerQuery))
    );
  }
 
  async getListSummary() {
    const lists = await this.fetchLists();
    
    const byCategory = this.getListsByCategory();
    
    return {
      total: lists.length,
      categories: Object.keys(byCategory),
      categoryBreakdown: Object.entries(byCategory).reduce((acc, [cat, items]) => {
        acc[cat] = items.length;
        return acc;
      }, {}),
      lists: lists.map(l => ({
        id: l.id,
        name: l.name,
        description: l.description,
        itemCount: l.itemCount || 0,
        createdAt: l.createdAt,
        updatedAt: l.updatedAt
      }))
    };
  }
 
  async getListDetails(id) {
    const list = await this.getListById(id);
    
    if (!list) {
      return {
        found: false,
        message: `List ${id} not found`
      };
    }
    
    return {
      found: true,
      ...list,
      createdDate: list.createdAt ? new Date(list.createdAt) : null,
      lastModified: list.updatedAt ? new Date(list.updatedAt) : null,
      age: list.createdAt ? Math.floor((Date.now() - new Date(list.createdAt)) / (1000 * 60 * 60 * 24)) : null
    };
  }
 
  async groupListsByName(pattern) {
    const lists = await this.fetchLists();
    const grouped = {};
    
    lists.forEach(list => {
      const match = list.name.match(pattern);
      const group = match ? match[1] : 'Other';
      
      if (!grouped[group]) {
        grouped[group] = [];
      }
      grouped[group].push(list);
    });
    
    return grouped;
  }
 
  clearCache() {
    this.cache = null;
    this.lastFetch = null;
  }
}
 
// Usage examples
const manager = new ProjectListManager("YOUR_API_KEY_HERE");
 
// Get all lists
const allLists = await manager.getAllLists();
console.log(`Total lists: ${allLists.length}`);
 
// Get specific list
const myList = await manager.getListById("list_123");
console.log("List:", myList);
 
// Get list by name
const industryList = await manager.getListByName("Technology");
console.log("Industry list:", industryList);
 
// Search lists
const searchResults = await manager.searchLists("series");
console.log(`Found ${searchResults.length} lists matching 'series'`);
 
// Get summary
const summary = await manager.getListSummary();
console.log("Summary:", summary);
 
// Get detailed info
const details = await manager.getListDetails("list_123");
console.log("Details:", details);
 
// Group by pattern
const grouped = await manager.groupListsByName(/^(\w+)\s/);
Object.entries(grouped).forEach(([group, lists]) => {
  console.log(`${group}: ${lists.length} lists`);
});
 
// Get list count
const count = await manager.getListCount();
console.log(`List count: ${count}`);

Result: Full-featured manager with search, filtering, and organization.

Python

Basic

CODE

import requests
 
API_KEY = "YOUR_API_KEY_HERE"
url = "https://api.kruncher.ai/api/integration/projectlists"
 
headers = {
    "Authorization": f"{API_KEY}",
    "Content-Type": "application/json"
}
 
response = requests.get(url, headers=headers)
 
if response.status_code == 200:
    lists = response.json()
    print(f"Total lists: {len(lists)}")
    
    for project_list in lists:
        print(f"- {project_list['name']} ({project_list['id']})")
        if 'description' in project_list:
            print(f"  Description: {project_list['description']}")
else:
    print(f"Error: {response.status_code} {response.text}")

Result: Retrieves and displays all project lists.

With Filtering

CODE

import requests
from typing import List, Dict, Optional
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
def get_project_lists() -> List[Dict]:
    """Get all project lists."""
    url = f"{BASE_URL}/integration/projectlists"
    
    headers = {
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json"
    }
    
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    
    return response.json()
 
def filter_lists_by_name(lists: List[Dict], search_term: str) -> List[Dict]:
    """Filter lists by name."""
    return [
        l for l in lists
        if search_term.lower() in l['name'].lower()
    ]
 
def get_list_by_id(lists: List[Dict], list_id: str) -> Optional[Dict]:
    """Get specific list by ID."""
    return next((l for l in lists if l['id'] == list_id), None)
 
def get_list_by_name(lists: List[Dict], name: str) -> Optional[Dict]:
    """Get specific list by name."""
    return next((l for l in lists if l['name'] == name), None)
 
def group_lists_by_field(lists: List[Dict], field: str) -> Dict[str, List[Dict]]:
    """Group lists by a specific field."""
    grouped = {}
    
    for project_list in lists:
        key = project_list.get(field, 'Uncategorized')
        if key not in grouped:
            grouped[key] = []
        grouped[key].append(project_list)
    
    return grouped
 
# Usage
lists = get_project_lists()
print(f"Total lists: {len(lists)}")
 
# Filter lists
tech_lists = filter_lists_by_name(lists, "technology")
print(f"Technology lists: {len(tech_lists)}")
 
# Get specific list
my_list = get_list_by_id(lists, "list_123")
if my_list:
    print(f"Found: {my_list['name']}")
 
# Get list by name
industry_list = get_list_by_name(lists, "Technology")
if industry_list:
    print(f"List: {industry_list}")
 
# Group lists
grouped = group_lists_by_field(lists, 'category')
for category, category_lists in grouped.items():
    print(f"{category}: {len(category_lists)} lists")

Result: Filtering and organizing with utility functions.

Advanced

CODE

import requests
import time
from typing import Dict, List, Optional
from datetime import datetime
 
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api"
 
class ProjectListManager:
    """Manage and organize project lists."""
    
    def __init__(self, api_key: str = API_KEY, cache_ttl: int = 300):
        self.api_key = api_key
        self.base_url = BASE_URL
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"{api_key}",
            "Content-Type": "application/json"
        })
        
        self.cache = None
        self.last_fetch = None
        self.cache_ttl = cache_ttl
    
    def fetch_lists(self, force_refresh: bool = False) -> List[Dict]:
        """
        Fetch all project lists with caching.
        
        Args:
            force_refresh: Force refresh even if cache is valid
        
        Returns:
            List of project list objects
        """
        now = time.time()
        
        if not force_refresh and self.cache and self.last_fetch:
            if (now - self.last_fetch) < self.cache_ttl:
                return self.cache
        
        response = self.session.get(f"{self.base_url}/integration/projectlists")
        response.raise_for_status()
        
        self.cache = response.json()
        self.last_fetch = now
        
        return self.cache
    
    def get_list_by_id(self, list_id: str) -> Optional[Dict]:
        """Get a specific list by ID."""
        lists = self.fetch_lists()
        return next((l for l in lists if l.get('id') == list_id), None)
    
    def get_list_by_name(self, name: str) -> Optional[Dict]:
        """Get a specific list by name."""
        lists = self.fetch_lists()
        return next((l for l in lists if l.get('name') == name), None)
    
    def search_lists(self, query: str) -> List[Dict]:
        """Search lists by name or description."""
        lists = self.fetch_lists()
        lower_query = query.lower()
        
        return [
            l for l in lists
            if lower_query in l.get('name', '').lower() or
               lower_query in l.get('description', '').lower()
        ]
    
    def get_all_lists(self) -> List[Dict]:
        """Get all project lists."""
        return self.fetch_lists()
    
    def get_list_count(self) -> int:
        """Get total number of lists."""
        return len(self.fetch_lists())
    
    def group_lists_by_field(self, field: str) -> Dict[str, List[Dict]]:
        """Group lists by a specific field."""
        lists = self.fetch_lists()
        grouped = {}
        
        for project_list in lists:
            key = project_list.get(field, 'Uncategorized')
            if key not in grouped:
                grouped[key] = []
            grouped[key].append(project_list)
        
        return grouped
    
    def get_lists_by_owner(self, owner: str) -> List[Dict]:
        """Get lists by owner/creator."""
        lists = self.fetch_lists()
        return [
            l for l in lists
            if l.get('owner') == owner or l.get('createdBy') == owner
        ]
    
    def get_list_summary(self) -> Dict:
        """Get comprehensive summary of all lists."""
        lists = self.fetch_lists()
        
        grouped = self.group_lists_by_field('category')
        
        return {
            'total': len(lists),
            'categories': list(grouped.keys()),
            'category_breakdown': {cat: len(items) for cat, items in grouped.items()},
            'lists': [
                {
                    'id': l.get('id'),
                    'name': l.get('name'),
                    'description': l.get('description'),
                    'item_count': l.get('itemCount', 0),
                    'created_at': l.get('createdAt'),
                    'updated_at': l.get('updatedAt')
                }
                for l in lists
            ]
        }
    
    def get_list_details(self, list_id: str) -> Dict:
        """Get detailed information about a list."""
        project_list = self.get_list_by_id(list_id)
        
        if not project_list:
            return {
                'found': False,
                'message': f"List {list_id} not found"
            }
        
        created_at = None
        updated_at = None
        age_days = None
        
        if project_list.get('createdAt'):
            created_at = datetime.fromisoformat(
                project_list['createdAt'].replace('Z', '+00:00')
            )
            age_days = (datetime.now(created_at.tzinfo) - created_at).days
        
        if project_list.get('updatedAt'):
            updated_at = datetime.fromisoformat(
                project_list['updatedAt'].replace('Z', '+00:00')
            )
        
        return {
            'found': True,
            **project_list,
            'created_date': created_at,
            'last_modified': updated_at,
            'age_in_days': age_days
        }
    
    def get_statistics(self) -> Dict:
        """Get statistics about project lists."""
        lists = self.fetch_lists()
        
        total_items = sum(l.get('itemCount', 0) for l in lists)
        
        return {
            'total_lists': len(lists),
            'total_items': total_items,
            'avg_items_per_list': total_items / len(lists) if lists else 0,
            'largest_list': max(
                (l for l in lists),
                key=lambda l: l.get('itemCount', 0),
                default=None
            ),
            'smallest_list': min(
                (l for l in lists),
                key=lambda l: l.get('itemCount', 0),
                default=None
            )
        }
    
    def clear_cache(self) -> None:
        """Clear the list cache."""
        self.cache = None
        self.last_fetch = None
 
# Usage examples
manager = ProjectListManager()
 
# Get all lists
all_lists = manager.get_all_lists()
print(f"Total lists: {len(all_lists)}")
 
# Get specific list
my_list = manager.get_list_by_id("list_123")
print(f"List: {my_list}")
 
# Search lists
results = manager.search_lists("series")
print(f"Found {len(results)} lists matching 'series'")
 
# Get summary
summary = manager.get_summary()
print(f"Summary: {summary}")
 
# Get statistics
stats = manager.get_statistics()
print(f"Statistics: {stats}")
 
# Get detailed info
details = manager.get_list_details("list_123")
print(f"Details: {details}")
 
# Group by category
grouped = manager.group_lists_by_field("category")
for category, lists_in_category in grouped.items():
    print(f"{category}: {len(lists_in_category)} lists")
 
# Get list count
count = manager.get_list_count()
print(f"Total lists: {count}")

Result: Production-ready manager with caching, search, and analytics.

cURL

Basic

CODE

curl -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Pretty Print

CODE

# Get all lists formatted nicely
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.'
 
# Get just list names and IDs
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.[] | {id: .id, name: .name, description: .description}'
 
# Count total lists
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '. | length'

Filter

CODE

# Find list by name
LIST_NAME="Technology"
 
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq ".[] | select(.name == \"$LIST_NAME\")"
 
# Find lists containing keyword
KEYWORD="series"
 
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq ".[] | select(.name | contains(\"$KEYWORD\"))"
 
# Get lists with item count
curl -s -X GET "https://api.kruncher.ai/api/integration/projectlists" \
  -H "Authorization: YOUR_API_KEY_HERE" \
  | jq '.[] | {name: .name, items: .itemCount}'

Response Structure

Success Response (200 OK)

CODE

[
  {
    "id": "list_abc123",
    "name": "Technology Startups",
    "description": "All technology-focused companies in portfolio",
    "category": "industry",
    "itemCount": 15,
    "owner": "team@company.com",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:20:00Z",
    "isActive": true,
    "createdBy": "team@company.com"
  },
  {
    "id": "list_def456",
    "name": "Series A Investments",
    "description": "Companies raising Series A",
    "category": "stage",
    "itemCount": 8,
    "owner": "investment@company.com",
    "createdAt": "2024-01-10T09:15:00Z",
    "updatedAt": "2024-01-21T11:45:00Z",
    "isActive": true,
    "createdBy": "investment@company.com"
  }
]

Response Fields

Field	Type	Description
`id`	string	Unique list identifier
`name`	string	Display name of the list
`description`	string	Description of list purpose
`category`	string	Type of list (industry, stage, geography, etc.)
`itemCount`	integer	Number of items in list
`owner`	string	Email or ID of list owner
`createdAt`	string	ISO 8601 timestamp when created
`updatedAt`	string	ISO 8601 timestamp when last updated
`isActive`	boolean	Whether list is currently active
`createdBy`	string	Who created the list

Common Use Cases

Organize by Industry

CODE

const manager = new ProjectListManager(API_KEY);
 
// Find industry-related lists
const industryLists = await manager.searchLists("technology");
industryLists.forEach(list => {
  console.log(`${list.name}: ${list.itemCount} companies`);
});

Filter by Stage

CODE

manager = ProjectListManager()
 
# Get all lists and filter
all_lists = manager.get_all_lists()
stage_lists = [l for l in all_lists if l.get('category') == 'stage']
 
for list in stage_lists:
    print(f"{list['name']}: {list['itemCount']} companies")

Create Report by List

CODE

async function generateListReport() {
  const manager = new ProjectListManager(API_KEY);
  const summary = await manager.getListSummary();
  
  console.log("Project Lists Report");
  console.log("===================");
  console.log(`Total Lists: ${summary.total}`);
  console.log("\nBy Category:");
  
  Object.entries(summary.categoryBreakdown).forEach(([category, count]) => {
    console.log(`  ${category}: ${count}`);
  });
  
  console.log("\nDetailed Lists:");
  summary.lists.forEach(list => {
    console.log(`  ${list.name}: ${list.itemCount} items`);
  });
}

Find Lists by Owner

CODE

manager = ProjectListManager()
 
# Get lists created by specific person
my_lists = manager.get_lists_by_owner("john@company.com")
print(f"Lists created by john: {len(my_lists)}")
 
for list in my_lists:
    print(f"  - {list['name']} ({list['itemCount']} items)")

Best Practices

Cache Management

Cache lists for 5-10 minutes
Refresh after creating/updating lists
Use force refresh sparingly
Share cache across requests

Organizing Lists

Use consistent naming conventions
Group related lists by category
Keep descriptions clear and concise
Archive unused lists

Performance

Cache results locally
Fetch once and reuse
Filter on client side after fetch
Don’t fetch for every request

Search & Discovery

Use meaningful list names
Add descriptive descriptions
Organize with consistent categories
Regular maintenance of list structure

Find Companies - Get projects in lists
Create Company - Add projects to lists
Update Project Status - Track project status
Get Mappings - Map to external systems

Troubleshooting

No Lists Returned

Verify API key is correct
Check if lists have been created
Ensure account has lists configured
Contact support if no lists exist

Lists Out of Date

Cache may be stale
Force refresh cache
Check update timestamps
Verify list modifications

Performance Issues

Large number of lists (>1000)
Implement client-side caching
Consider pagination if available
Contact support for optimization

List Not Found

Verify list ID or name
Check if list was deleted
Ensure you have access
Search for similar names

Need Help?

Create lists? Contact support for configuration
Bulk operations? Ask about batch list management
Custom categories? Discuss organization structure
Integration? See mapping and sync endpoints

Find Lists

Endpoint

Headers

Use Cases

When to Use This Endpoint

Code Examples

JavaScript/TypeScript

Basic

With Filtering

Advanced

Python

Basic

With Filtering

Advanced

cURL

Basic

Pretty Print

Filter

Response Structure

Success Response (200 OK)

Response Fields

Common Use Cases

Organize by Industry

Filter by Stage

Create Report by List

Find Lists by Owner

Best Practices

Cache Management

Organizing Lists

Performance

Search & Discovery

Related Endpoints

Troubleshooting

No Lists Returned

Lists Out of Date

Performance Issues

List Not Found

Need Help?