Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt

Use this file to discover all available pages before exploring further.

For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending .md to its URL or sending Accept: text/markdown.
Timeline: Both APIs are currently available. Include the parallel-beta: "findall-2025-09-15" header to use V1 API. Without this header, requests default to V0 API.

​
Why Migrate to V1?

V1 delivers significant improvements across pricing, performance, and capabilities:
  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:
  4. Better Performance: Improved latency and match quality across all stages
Breaking Changes: V1 is not backward compatible. V0 runs cannot be accessed via V1 endpoints. Parameter names, response schemas, and pricing have changed.

​
Key Differences

​
Request Structure

V0 used a nested findall_spec object. V1 flattens this structure:
ConceptV0 APIV1 API
Required HeaderNoneparallel-beta: "findall-2025-09-15"
Search Goalqueryobjective
Entity Typefindall_spec.nameentity_type
Filter Criteriafindall_spec.columns (type=constraint)match_conditions
Model Selectionprocessorgenerator
Max Resultsresult_limit (max: 200)match_limit (max: 1,000)

​
Response Structure

V0 included results in poll responses. V1 separates status and results:
ConceptV0 APIV1 API
Status Checkis_active + are_enrichments_activestatus.is_active
Get ResultsGET /v1beta/findall/runs/{id} (included in response)GET /v1beta/findall/runs/{id}/result
Results Arrayresultscandidates
Relevance Scorescorerelevance_score
Match Datafilter_results (array)output (object)
Field AccessLoop through array to find keyDirect: output[field_name]["value"]

​
Enrichment Handling

V0 included enrichments in initial spec. V1 adds them via separate endpoint:
AspectV0 APIV1 API
DefinitionPart of columns array (type=enrichment)Separate POST /v1beta/findall/runs/{id}/enrich call
TimingAt run creation onlyAnytime after run creation (multiple enrichments supported)
Output FormatSeparate enrichment_results arrayMerged into output object with type=enrichment
Processor OptionsLimited to FindAll processorsAll Task API processors available

​
End-to-End Migration Example

This example shows the complete workflow migration, including enrichments: 
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']}")

​
Migration Checklist

Complete these steps to migrate from V0 to V1:

​
Core Changes

  • Add parallel-beta: "findall-2025-09-15" header to all requests
  • 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

​
Core Concepts

​
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