FindAll API

Overview

The Parallel FindAll API enables you to discover and research entities from across the web using natural language. It turns questions like “Find all AI companies that raised Series A funding recently” into structured, enriched databases with verified information.

Alpha Notice: The FindAll API is currently in public alpha. Endpoints and request/response formats are subject to change. We will provide 30 days’ notice before any breaking changes. For production access, contact support@parallel.ai.

Key Features

FindAll excels at entity discovery and research tasks that require both breadth and depth:

Natural Language Input: Express complex search criteria in plain English
Intelligent Entity Discovery: Automatically generates and validates potential matches
Structured Enrichment: Extract specific attributes for each discovered entity
Citation-backed Results: Every data point includes reasoning and source citations
Asynchronous Processing: Handle large-scale searches without blocking your application

Common Use Cases

Market Mapping: “Find all fintech companies offering earned-wage access in Brazil”
Competitive Intelligence: “Find all AI infrastructure providers that raised Series B funding in the last 6 months”
Lead Generation: “Find all residential roofing companies in Charlotte, NC”
Financial Research: “Find all S&P 500 stocks that dropped X% in last 30 days and listed tariffs as a key risk”

How It Works

The FindAll API follows a three-step asynchronous workflow:

Ingest: Convert your natural language query into a structured FindAllSpec
Run: Execute the FindAllSpec to start the discovery process
Poll: Check status and retrieve results as they become available

Natural Language Query → FindAllSpec → findall_id → Structured Results

Authentication

All requests require an API key in the header:

x-api-key: PARALLEL_API_KEY

Endpoints

1. Ingest Query

Convert a natural language query into a structured FindAllSpec.

curl -X POST https://api.parallel.ai/v1beta/findall/ingest \
  -H "x-api-key: PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find all AI companies that recently raised money and get their website, CEO name, and CTO name."
  }'

Ingest Response Example

{
  "name": "funded_companies",
  "columns": [
    {
      "name": "entity_name",
      "description": "Name of the funded company",
      "type": "enrichment",
      "order_direction": null
    },
    {
      "name": "website",
      "description": "Website of the funded company",
      "type": "enrichment",
      "order_direction": null
    },
    {
      "name": "ai_product_development_evidence",
      "description": "Evidence of AI product development: description of AI products/services, core AI technologies used, and target applications.",
      "type": "enrichment",
      "order_direction": null
    },
    {
      "name": "series_a_2024_funding_evidence",
      "description": "Evidence of Series A funding in 2024: funding amount in USD, date of funding (YYYY-MM-DD), lead investors, and total funding raised to date.",
      "type": "enrichment",
      "order_direction": null
    },
    {
      "name": "ai_product_development_check",
      "description": "Company must be developing products or services in the field of artificial intelligence (AI).",
      "type": "constraint",
      "order_direction": null
    },
    {
      "name": "series_a_2024_funding_check",
      "description": "Company must have received Series A funding in 2024.",
      "type": "constraint",
      "order_direction": null
    }
  ],
  "query": "Find all companies developing AI products that raised Series A funding in 2024",
  "title": "AI companies with 2024 Series A"
}

2. Run FindAll

Start a FindAll run using the structured query from the ingest step.

curl -X POST https://api.parallel.ai/v1beta/findall/runs \
  -H "x-api-key: PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "findall_spec": {
      "name": "funded_companies",
      "columns": [
        {"name": "entity_name", "description": "Name of the funded company", "type": "enrichment"},
        {"name": "website", "description": "Website of the funded company", "type": "enrichment"},
        {"name": "ai_product_development_check", "description": "Company develops AI products", "type": "constraint"},
        {"name": "series_a_2024_funding_check", "description": "Company raised Series A in 2024", "type": "constraint"}
      ]
    },
    "processor": "base",
    "result_limit": 200
  }'

Request Parameters

Field	Type	Required	Description
findall_spec	FindAllSpec	Yes	The structured query from ingest
candidates	array	No	Optional seed entities to include
processor	string	No	Quality/cost tradeoff: `base` or `pro` (default: base)
result_limit	integer	No	Maximum results to return (default: 200)
metadata	object	No	Custom key-value pairs for tracking

Run Response Example

{
  "findall_id": "findall_de9bbbed-1021-48fe-af79-2faca7177230_339277cf-b70e-4b49-9711-5bd91f803cad",
  "status": "queued"
}

3. Poll for Results

Check the status of your FindAll run and retrieve results. Important: A run is complete only when both is_active and are_enrichments_active are false.

curl -X GET "https://api.parallel.ai/v1beta/findall/runs/YOUR_FINDALL_ID" \
  -H "x-api-key: PARALLEL_API_KEY"

Response Structure

{
  "title": "AI companies with 2024 Series A",
  "query": "Find all companies developing AI products that raised Series A funding in 2024",
  "spec": {
    "name": "funded_companies",
    "columns": [
      {
        "name": "ai_product_development_check",
        "description": "Company must be developing products or services in the field of artificial intelligence AI.",
        "type": "constraint",
        "status": null
      },
      {
        "name": "series_a_2024_funding_check",
        "description": "Company must have received Series A funding in 2024.",
        "type": "constraint",
        "status": null
      }
    ]
  },
  "is_active": false,
  "are_enrichments_active": false,
  "status": "completed",
  "steps": [
    {
      "name": "understanding_question",
      "description": "Understand the question",
      "status": "done"
    },
    {
      "name": "gen_candidates_step",
      "description": "Generate candidates using Parallel Index",
      "status": "done"
    },
    {
      "name": "filter_candidates_step",
      "description": "Process candidates using Parallel Processors",
      "status": "done"
    }
  ],
  "filters": [
    {
      "name": "ai_product_development_check",
      "description": "Company must be developing products or services in the field of artificial intelligence AI.",
      "type": "filter",
      "status": "done"
    },
    {
      "name": "series_a_2024_funding_check",
      "description": "Company must have received Series A funding in 2024.",
      "type": "filter",
      "status": "done"
    }
  ],
  "enrichments": [
    {
      "name": "series_a_2024_funding_evidence",
      "description": "Evidence of Series A funding in 2024: funding amount in USD, date of funding (YYYY-MM-DD), lead investors, and total funding raised to date.",
      "type": "enrichment",
      "status": "done"
    },
    {
      "name": "ai_product_development_evidence",
      "description": "Evidence of AI product development: description of AI products/services, core AI technologies used, and target applications.",
      "type": "enrichment",
      "status": "done"
    }
  ],
  "results": [
    {
      "entity_id": "6d5f6411-9554-4168-b4ad-75b0439f03b7",
      "name": "Cognition AI",
      "url": "cognition.ai",
      "description": "",
      "filter_results": [
        {
          "key": "ai_product_development_check",
          "value": "yes",
          "reasoning": "Cognition AI is described as an applied AI lab that is building the future of software engineering and the makers of Devin, an AI software developer.",
          "citations": "https://cognition.ai/blog/introducing-devin, https://research.contrary.com/company/cognition",
          "confidence": "high"
        },
        {
          "key": "series_a_2024_funding_check",
          "value": "yes",
          "reasoning": "Multiple sources confirm that Cognition AI received Series A funding in 2024.",
          "citations": "https://www.crunchbase.com/funding_round/cognition-5bd7-series-a--d0b08732, https://techcrunch.com/2024/12/20/heres-the-full-list-of-49-us-ai-startups-that-have-raised-100m-or-more-in-2024/",
          "confidence": "high"
        }
      ],
      "enrichment_results": [],
      "score": 100.0
    }
  ],
  "candidates": [
    {
      "entity_id": "0b330c38-0034-4f37-b4fe-bdda3e1bdb5c",
      "name": "Abridge"
    },
    {
      "entity_id": "93fcc889-ed9a-4b45-8bd8-b48a79fd0717",
      "name": "Aurora AI"
    }
  ],
  "max_results": 20,
  "modified_at": "2025-08-06T22:31:56.473269Z",
  "created_at": "2025-08-06T22:31:10.025762",
  "pages_read": 307,
  "pages_considered": 1784,
  "billing_metrics": {
    "cost_mode": "base",
    "rows_processed": 6,
    "enrichment_cells": 8
  }
}

4. Additional Operations

Cancel a Run

Stop a running FindAll operation:

curl -X POST https://api.parallel.ai/v1beta/findall/runs/cancel \
  -H "x-api-key: PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"findall_id": "YOUR_FINDALL_ID"}'

Billing Notice: You will still be charged for any processing completed before the cancellation. This includes the generator cost and any constraint/enrichment evaluations that finished prior to cancellation.

Extend a Run

Add more entities to a completed run:

curl -X POST https://api.parallel.ai/v1beta/findall/runs/extend \
  -H "x-api-key: PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "findall_id": "YOUR_FINDALL_ID",
    "num_entities": 100
  }'

Data Models

Column Types

FindAll uses two types of columns:

Constraint: Boolean criteria that entities must satisfy (e.g., “is an AI company”)
Enrichment: Attributes to extract for matching entities (e.g., “CEO name”)

Constraint Results

Constraint results can have the following values:

yes: Entity clearly meets the criteria
not_sure: Insufficient information
no: Entity does not meet criteria
skipped: Constraint not evaluated

Each constraint result also includes:

confidence: Level of confidence in the result (high, medium, low)
reasoning: Detailed explanation of the decision
citations: URLs supporting the reasoning

Entity Scoring

Each result includes:

score: Score to rank the results, higher means better match for constraints
pages_read: Number of web pages analyzed for this entity
pages_considered: Total pages evaluated for this entity

Response Metadata

Poll responses include additional metadata:

pages_read: Total web pages analyzed across all entities
pages_considered: Total web pages evaluated across all entities
billing_metrics: Cost tracking information
- cost_mode: Processor used (base or pro)
- rows_processed: Number of entities processed
- enrichment_cells: Number of enrichment fields populated
are_enrichments_active: Whether enrichments are still running
filters: Array of constraint definitions with status
enrichments: Array of enrichment definitions with status

Important: When polling, check both is_active AND are_enrichments_active to determine if the run is truly complete. A run is finished only when both fields are false.

Processing Steps

FindAll runs follow these steps:

understanding_question: Parse and understand the natural language query
gen_candidates_step: Generate potential entity candidates using Parallel Index
filter_candidates_step: Process candidates using constraints and enrichments

Each step has a status field: running, done, or failed.

Quickstart

Get started with FindAll in three simple steps. We’ll find AI companies that raised Series A funding in 2024. (Or copy the docs and let your favourite LLM write the code for you).

Step 1: Ingest Your Query

Convert your natural language question into a structured FindAllSpec:

import requests

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

query = "Find all AI companies that raised Series A funding in 2024"

ingest_response = requests.post(
    f"{BASE_URL}/v1beta/findall/ingest",
    headers={"x-api-key": API_KEY},
    json={"query": query}
)

findall_spec = ingest_response.json()
print(f"Generated spec with {len(findall_spec['columns'])} columns")

Sample Response:

{
  "name": "funded_companies",
  "columns": [
    {
      "name": "entity_name",
      "description": "Name of the funded company",
      "type": "enrichment",
      "order_direction": null
    },
    {
      "name": "ai_product_development_check",
      "description": "Company must be developing products or services in the field of artificial intelligence (AI).",
      "type": "constraint",
      "order_direction": null
    },
    {
      "name": "series_a_2024_funding_check",
      "description": "Company must have received Series A funding in 2024.",
      "type": "constraint",
      "order_direction": null
    }
  ],
  "query": "Find all companies developing AI products that raised Series A funding in 2024",
  "title": "AI companies with 2024 Series A"
}

Step 2: Start Your FindAll Run

Execute the FindAllSpec to begin discovering companies:

run_response = requests.post(
    f"{BASE_URL}/v1beta/findall/runs",
    headers={"x-api-key": API_KEY},
    json={
        "findall_spec": findall_spec,
        "processor": "base",
        "result_limit": 50
    }
)

findall_id = run_response.json()["findall_id"]
print(f"Started FindAll run: {findall_id}")

Sample Response:

{
  "findall_id": "findall_de9bbbed-1021-48fe-af79-2faca7177230_339277cf-b70e-4b49-9711-5bd91f803cad",
  "status": "queued"
}

Step 3: Poll for Results

Check the status and retrieve your results:

import time

while True:
    poll_response = requests.get(
        f"{BASE_URL}/v1beta/findall/runs/{findall_id}",
        headers={"x-api-key": API_KEY}
    )

    result = poll_response.json()

    print(f"Status: {result['status']}, Results: {len(result['results'])}")

    if not result["is_active"] and not result["are_enrichments_active"]:
        break

    time.sleep(15)  # Poll every 15 seconds

# Process results
print(f"\nFound {len(result['results'])} companies:")
for entity in result['results'][:3]:  # Show first 3
    print(f"- {entity['name']} (Score: {entity['score']})")

Sample Response:

{
  "is_active": false,
  "status": "completed",
  "results": [
    {
      "entity_id": "6d5f6411-9554-4168-b4ad-75b0439f03b7",
      "name": "Cognition AI",
      "url": "cognition.ai",
      "description": "",
      "filter_results": [
        {
          "key": "ai_product_development_check",
          "value": "yes",
          "reasoning": "Cognition AI is described as an applied AI lab that is building the future of software engineering and the makers of Devin, an AI software developer.",
          "citations": "https://cognition.ai/blog/introducing-devin, https://research.contrary.com/company/cognition",
          "confidence": "high"
        },
        {
          "key": "series_a_2024_funding_check",
          "value": "yes",
          "reasoning": "Multiple sources confirm that Cognition AI received Series A funding in 2024.",
          "citations": "https://www.crunchbase.com/funding_round/cognition-5bd7-series-a--d0b08732",
          "confidence": "high"
        }
      ],
      "enrichment_results": [],
      "score": 100.0
    }
  ],
  "candidates": [
    {
      "entity_id": "0b330c38-0034-4f37-b4fe-bdda3e1bdb5c",
      "name": "Abridge"
    }
  ],
  "max_results": 20,
  "pages_read": 307,
  "pages_considered": 1784
}

Complete Example

Here’s the full workflow in one script:

import requests
import time

# Configuration
API_KEY = "PARALLEL_API_KEY"
BASE_URL = "https://api.parallel.ai"

def run_findall_query(query):
    # Step 1: Ingest the query
    ingest_response = requests.post(
        f"{BASE_URL}/v1beta/findall/ingest",
        headers={"x-api-key": API_KEY},
        json={"query": query}
    )
    findall_spec = ingest_response.json()
    print(f"✓ Generated spec with {len(findall_spec['columns'])} columns")

    # Step 2: Run FindAll
    run_response = requests.post(
        f"{BASE_URL}/v1beta/findall/runs",
        headers={"x-api-key": API_KEY},
        json={
            "findall_spec": findall_spec,
            "processor": "base",
            "result_limit": 50
        }
    )
    findall_id = run_response.json()["findall_id"]
    print(f"✓ Started FindAll run: {findall_id}")

    # Step 3: Poll for results
    while True:
        poll_response = requests.get(
            f"{BASE_URL}/v1beta/findall/runs/{findall_id}",
            headers={"x-api-key": API_KEY}
        )
        result = poll_response.json()

        print(f"Status: {result['status']}, Results: {len(result['results'])}")

        if not result["is_active"] and not result["are_enrichments_active"]:
            break
        time.sleep(15)

    # Display results
    print(f"\n✓ Found {len(result['results'])} companies:")
    for entity in result['results'][:5]:
        print(f"  • {entity['name']} (Score: {entity['score']})")

    return result

# Run the example
if __name__ == "__main__":
    query = "Find all AI companies that raised Series A funding in 2024"
    results = run_findall_query(query)

Pricing

FindAll pricing reflects the comprehensive research performed:

Cost Components

Generator (per query)
- base: $1.00
- pro: $5.00
Constraint
- Per candidate evaluated, independent of number of constraints
- base: $0.030
- pro: $0.200
Enrichment
- Per enrichment, depends on number of enrichments. Run only on candidates fully matching all the constraints
- base: $0.010
- pro: $0.100

Example Calculations

Simple Example - Constraint-only query with 100 candidates using base processor:

Generator: $1.00
Constraint: 100 entities × $0.03 =$ 3.00
Total Cost: $4.00

Complex Example - Query with 100 candidates, constraints + enrichments using base processor:

Generator: $1.00
Constraint: 100 entities × $0.03 =$ 3.00
Enrichment: 50 matches × 3 fields × $0.01 =$ 1.50
Total Cost: $5.50

Best Practices

Start with Clear Queries: Be specific about your criteria and desired attributes
Use Appropriate Processors: Choose base for a balance of cost and quality, pro for maximum accuracy
Set Reasonable Limits: Balance between coverage and cost
Poll Efficiently: Check every 15-30 seconds to avoid rate limits
Handle Partial Results: Process results as they arrive for better UX

Rate Limits

Contact support@parallel.ai for production limits

Support

For questions or production access, contact our team:

Email: support@parallel.ai
Documentation: docs.parallel.ai

Task API

Search API

Chat API

Additional Resources

FindAll API

Overview

Key Features

Common Use Cases

How It Works

Authentication

Endpoints

1. Ingest Query

Ingest Response Example

2. Run FindAll

Request Parameters

Run Response Example

3. Poll for Results

Response Structure

4. Additional Operations

Cancel a Run

Extend a Run

Data Models

Column Types

Constraint Results

Entity Scoring

Response Metadata

Processing Steps

Quickstart

Step 1: Ingest Your Query

Step 2: Start Your FindAll Run

Step 3: Poll for Results

Complete Example

Pricing

Cost Components

Example Calculations

Best Practices

Rate Limits

Support

Task API

Search API

Chat API

FindAll API

Additional Resources

​Overview

​Key Features

​Common Use Cases

​How It Works

​Authentication

​Endpoints

​1. Ingest Query

​Ingest Response Example

​2. Run FindAll

​Request Parameters

​Run Response Example

​3. Poll for Results

​Response Structure

​4. Additional Operations

​Cancel a Run

​Extend a Run

​Data Models

​Column Types

​Constraint Results

​Entity Scoring

​Response Metadata

​Processing Steps

​Quickstart

​Step 1: Ingest Your Query

​Step 2: Start Your FindAll Run

​Step 3: Poll for Results

​Complete Example

​Pricing

​Cost Components

​Example Calculations

​Best Practices

​Rate Limits

​Support

Overview

Key Features

Common Use Cases

How It Works

Authentication

Endpoints

1. Ingest Query

Ingest Response Example

2. Run FindAll

Request Parameters

Run Response Example

3. Poll for Results

Response Structure

4. Additional Operations

Cancel a Run

Extend a Run

Data Models

Column Types

Constraint Results

Entity Scoring

Response Metadata

Processing Steps

Quickstart

Step 1: Ingest Your Query

Step 2: Start Your FindAll Run

Step 3: Poll for Results

Complete Example

Pricing

Cost Components

Example Calculations

Best Practices

Rate Limits

Support