FindAll Migration Guide

​

Why Migrate to V1?

1. Pay-per-Match Pricing: Charges based on matches found, not candidates evaluated
2. Task-Powered Enrichments: Flexible enrichments via Task API with expanded processor options
3. Enhanced Capabilities:
   • Extend, Cancel, and Preview endpoints
   • Real-time streaming with incremental updates
   • Exclude candidates from evaluation
   • Match conditions return both value and is_matched boolean
   • Increased match_limit from 200 to 1,000
4. Better Performance: Improved latency and match quality across all stages

​

Key Differences

​

Request Structure

​

Response Structure

​

Enrichment Handling

​

End-to-End Migration Example

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://api.parallel.ai"

# Step 1: Ingest query
ingest_response = requests.post(
    f"{BASE_URL}/v1beta/findall/ingest",
    headers={"x-api-key": API_KEY},
    json={"query": "Find AI companies that raised Series A in 2024 and get CEO names"}
)
findall_spec = ingest_response.json()

# Step 2: Create run (constraints + enrichments together)
run_response = requests.post(
    f"{BASE_URL}/v1beta/findall/runs",
    headers={"x-api-key": API_KEY},
    json={
        "findall_spec": findall_spec,
        "processor": "core",
        "result_limit": 100
    }
)
findall_id = run_response.json()["findall_id"]

# Step 3: Poll until both flags are false
while True:
    poll_response = requests.get(
        f"{BASE_URL}/v1beta/findall/runs/{findall_id}",
        headers={"x-api-key": API_KEY}
    )
    result = poll_response.json()
    if not result["is_active"] and not result["are_enrichments_active"]:
        break
    time.sleep(15)

# Step 4: Access results from poll response
for entity in result["results"]:
    print(f"{entity['name']}: Score {entity['score']}")

    # Loop through arrays to find values
    for filter_result in entity["filter_results"]:
        print(f"  {filter_result['key']}: {filter_result['value']}")
    for enrichment in entity["enrichment_results"]:
        print(f"  {enrichment['key']}: {enrichment['value']}")

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://api.parallel.ai"
headers = {
    "x-api-key": API_KEY
}

# Step 1: Ingest objective
ingest_response = requests.post(
    f"{BASE_URL}/v1beta/findall/ingest",
    headers=headers,
    json={"objective": "Find AI companies that raised Series A in 2024 and get CEO names"}
)
ingest_data = ingest_response.json()

# Step 2: Create run (constraints only, flattened)
run_response = requests.post(
    f"{BASE_URL}/v1beta/findall/runs",
    headers=headers,
    json={
        "objective": ingest_data["objective"],
        "entity_type": ingest_data["entity_type"],
        "match_conditions": ingest_data["match_conditions"],
        "generator": "core",
        "match_limit": 50
    }
)
findall_id = run_response.json()["findall_id"]

# Step 3: Add enrichments (separate call)
time.sleep(5)
requests.post(
    f"{BASE_URL}/v1beta/findall/runs/{findall_id}/enrich",
    headers=headers,
    json={
        "processor": "core",
        "output_schema": ingest_data.get("enrichments")[0]
    }
)

# Step 4: Poll until completed
while True:
    status_response = requests.get(
        f"{BASE_URL}/v1beta/findall/runs/{findall_id}",
        headers=headers
    )
    if status_response.json()["status"]["status"] == "completed":
        break
    time.sleep(10)

# Step 5: Fetch results from separate endpoint
result_response = requests.get(
    f"{BASE_URL}/v1beta/findall/runs/{findall_id}/result",
    headers=headers
)
result = result_response.json()

# Step 6: Access results with direct object access
for candidate in result["candidates"]:
    if candidate["match_status"] == "matched":
        print(f"{candidate['name']}: Score {candidate['relevance_score']}")

        # Direct access to all fields (constraints + enrichments merged)
        for field_name, field_data in candidate["output"].items():
            print(f"  {field_name}: {field_data['value']}")

​

Migration Checklist

​

Core Changes

• Change ingest parameter: query → objective
• Flatten run request: extract objective, entity_type, match_conditions from findall_spec
• Rename: result_limit → match_limit, processor → generator
• Update status check: status.status == "completed" instead of checking two flags
• Fetch results from separate /result endpoint
• Update result parsing: results → candidates, score → relevance_score
• Change field access: direct object access (output[field]) vs array iteration

​

Enrichment Changes (if applicable)

• Move enrichments to separate POST /enrich call after run creation
• Convert enrichment columns to output_schema format (see Task API)
• Update result access: enrichments now merged into output object

​

Optional Enhancements

• Implement streaming via /events endpoint for real-time updates
• Add exclude_list to filter out specific candidates
• Use preview: true for testing queries before full runs
• Implement /extend endpoint to increase match limits dynamically
• Implement /cancel endpoint to stop runs early

​

Testing

• Validate queries in development environment
• Review pricing impact with generator-based model
• Update error handling for new response schemas
• Monitor performance metrics

​

Related Topics

​

Core Concepts

• Quickstart: Get started with V1 FindAll API
• Candidates: Understand candidate object structure and states
• Generators and Pricing: Understand generator options and pricing
• Run Lifecycle: Understand run statuses and termination

​

Features

• Preview: Test queries with ~10 candidates before running full searches
• Enrichments: Extract additional structured data for matched candidates
• Extend Runs: Increase match limits without paying new fixed costs
• Cancel Runs: Stop runs early to save costs
• Streaming Events: Receive real-time updates via Server-Sent Events
• Webhooks: Configure HTTP callbacks for run completion and matches