FindAll API Quickstart

Beta Notice: Parallel FindAll is currently in public beta. Endpoints and request/response formats are subject to change. We will provide 30 days notice before any breaking changes.

What is FindAll?

FindAll is a web-scale entity discovery system that turns natural language queries into structured, enriched databases of companies, people, and other real-world entities. It answers questions like “FindAll AI companies that raised Series A funding in the last 3 months” by combining intelligent search, evaluation, and enrichment capabilities. Unlike traditional search APIs that return a fixed set of results, FindAll generates candidates from web data, validates them against your criteria, and optionally enriches matches with additional structured information—all from a single natural language query.

Need results in seconds? Entity Search is FindAll’s fast, synchronous counterpart for people-and-company search, optimized for recall and speed where FindAll is optimized for precision. It returns a set of matching results in seconds, without FindAll’s verification, enrichment, or citations. Use it when latency matters more than precision.

Key Features & Use Cases

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: Evaluated fields can include reasoning and source citations through basis
Asynchronous Processing: Handle large-scale searches without blocking your application

Pricing

See Pricing for a detailed schedule of rates.

Common Use Cases

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

What Happens During a Run

When you create a FindAll run, the system executes three key stages:

Generate Candidates from Web Data: FindAll searches across the web to identify potential entities that might match your query. Each candidate enters the generated status.
Evaluate Candidates Based on Match Conditions: Each generated candidate is evaluated against your match conditions. Candidates that satisfy all conditions reach matched status; those that do not become unmatched. The result snapshot can include both groups, so filter on match_status when you need only successful matches.
Extract Enrichments for Matched Candidates: After you add an enrichment through /enrich, FindAll uses the Task API to extract those fields for matched candidates and handles the orchestration automatically.

This three-stage approach ensures efficiency: you only pay to enrich candidates that actually match your criteria.

Quick Example

Here’s a complete example that finds portfolio companies. The workflow consists of four steps: converting natural language to a schema, starting the run, polling for completion, and retrieving results.

The Basic Workflow

The FindAll API follows a simple four-step workflow:

Ingest: Convert your natural language query into a structured schema
Run: Start the findall run to discover and match candidates
Poll: Check status until the run reaches a terminal state
Fetch: Retrieve the current candidate snapshot and any available reasoning and citations

Natural Language Query → Structured Schema → findall_id → Candidate Snapshot

Step 1: Ingest

Purpose: Converts your natural language query into a structured schema with entity_type and match_conditions. The ingest endpoint automatically extracts:

What type of entities to search for (companies, people, products, etc.)
Match conditions that must be satisfied
Optional enrichment suggestions

Request:

curl -X POST "https://api.parallel.ai/v1beta/findall/ingest" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "FindAll portfolio companies of Khosla Ventures founded after 2020"
  }'

from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

findall_run = client.beta.findall.ingest(
    objective="FindAll portfolio companies of Khosla Ventures founded after 2020"
)

import Parallel from 'parallel-web';

const client = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY
});

const run = await client.beta.findall.ingest({
  objective: "FindAll portfolio companies of Khosla Ventures founded after 2020"
});

Response:

{
  "objective": "FindAll portfolio companies of Khosla Ventures founded after 2020",
  "entity_type": "companies",
  "match_conditions": [
    {
      "name": "khosla_ventures_portfolio_check",
      "description": "Company must be a portfolio company of Khosla Ventures."
    },
    {
      "name": "founded_after_2020_check",
      "description": "Company must have been founded after 2020."
    }
  ],
  "generator": "core"
}

Customizing the ingest schema

The ingest endpoint generates a suggested schema, but you can (and should) review and modify it before creating a run. Common modifications include:

Relaxing temporal conditions: Ingest may interpret phrases like “founded after 2023” strictly (e.g., “within the last 1 year”). You can broaden the description to be more inclusive.
Adjusting match condition descriptions: Make descriptions more or less specific to control match rates.
Adding or removing match conditions: Tailor the schema to your exact needs.
Changing the entity type: Correct the entity type if ingest misidentified it.

For example, if ingest generated a strict condition like "Company must have been founded within the last 1 year", you might change it to "Company must have been founded in 2025 or later" for more reliable matching.

The ingest schema is a starting point, not a final answer. Editing match_conditions between the ingest and create steps is the recommended way to refine your query for better results.

Step 2: Create FindAll Run

Purpose: Starts the asynchronous findall process to generate and evaluate candidates. You can use the schema from ingest directly, or modify it before passing it to the create endpoint. Key parameters:

generator: Choose preview, base, core, or pro based on your needs (see Generators and Pricing)
match_limit: For base, core, and pro, the maximum number of matches to find. For preview, the number of candidates to evaluate (5–10).

Request:

curl -X POST "https://api.parallel.ai/v1beta/findall/runs" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "FindAll portfolio companies of Khosla Ventures founded after 2020",
    "entity_type": "companies",
    "match_conditions": [
      {
        "name": "khosla_ventures_portfolio_check",
        "description": "Company must be a portfolio company of Khosla Ventures."
      },
      {
        "name": "founded_after_2020_check",
        "description": "Company must have been founded after 2020."
      }
    ],
    "generator": "core",
    "match_limit": 5
  }'

from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

findall_run = client.beta.findall.create(
    objective="FindAll portfolio companies of Khosla Ventures founded after 2020",
    entity_type="companies",
    match_conditions=[
        {
            "name": "khosla_ventures_portfolio_check",
            "description": "Company must be a portfolio company of Khosla Ventures."
        },
        {
            "name": "founded_after_2020_check",
            "description": "Company must have been founded after 2020."
        }
    ],
    generator="core",
    match_limit=5
)

import Parallel from 'parallel-web';

const client = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY
});

const run = await client.beta.findall.create({
  objective: "FindAll portfolio companies of Khosla Ventures founded after 2020",
  entity_type: "companies",
  match_conditions: [
    {
      name: "khosla_ventures_portfolio_check",
      description: "Company must be a portfolio company of Khosla Ventures."
    },
    {
      name: "founded_after_2020_check",
      description: "Company must have been founded after 2020."
    }
  ],
  generator: "core",
  match_limit: 5
});

Response:

{
  "findall_id": "findall_40e0ab8c10754be0b7a16477abb38a2f",
  "status": {
    "status": "queued",
    "is_active": true,
    "metrics": {
      "generated_candidates_count": 0,
      "matched_candidates_count": 0
    }
  },
  "generator": "core",
  "metadata": {},
  "created_at": "2025-11-03T20:47:21.580909Z",
  "modified_at": "2025-11-03T20:47:21.580909Z"
}

Step 3: Poll for Status

Purpose: Monitor progress and wait for completion. Request:

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

from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

run_status = client.beta.findall.retrieve(
    findall_id="findall_40e0ab8c10754be0b7a16477abb38a2f"
)

import Parallel from 'parallel-web';

const client = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY
});

const runStatus = await client.beta.findall.retrieve("findall_40e0ab8c10754be0b7a16477abb38a2f");

Response:

{
  "findall_id": "findall_40e0ab8c10754be0b7a16477abb38a2f",
  "status": {
    "status": "running",
    "is_active": true,
    "metrics": {
      "generated_candidates_count": 3,
      "matched_candidates_count": 1
    }
  },
  "generator": "core",
  "metadata": {},
  "created_at": "2025-11-03T20:47:21.580909Z",
  "modified_at": "2025-11-03T20:47:22.024269Z"
}

Step 4: Get Results

Purpose: Retrieve a snapshot of the run and the candidates available at request time, with match details and any available reasoning and citations. While a run is active, the snapshot can include generated candidates that have not finished evaluation. You can call this endpoint while the run is active or after it finishes.

To understand the complete candidate object structure, see Candidates.

Request:

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

from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

result = client.beta.findall.result(
    findall_id="findall_40e0ab8c10754be0b7a16477abb38a2f",
)

import Parallel from 'parallel-web';

const client = new Parallel({
  apiKey: process.env.PARALLEL_API_KEY
});

const result = await client.beta.findall.result("findall_40e0ab8c10754be0b7a16477abb38a2f");

Response: The example below shows one candidate from the full snapshot for brevity.

{
  "run": {
    "findall_id": "findall_40e0ab8c10754be0b7a16477abb38a2f",
    "status": {
      "status": "completed",
      "is_active": false,
      "metrics": {
        "generated_candidates_count": 8,
        "matched_candidates_count": 5
      },
      "termination_reason": "match_limit_met"
    },
    "generator": "core",
    "metadata": {},
    "created_at": "2025-11-03T20:47:21.580909Z",
    "modified_at": "2025-11-03T20:50:38.901124Z"
  },
  "candidates": [
    {
      "candidate_id": "candidate_a062dd17-d77a-4b1b-ad0e-de113e82f838",
      "name": "Figure AI",
      "url": "https://www.figure.ai",
      "description": "AI robotics company building general purpose humanoid robots",
      "match_status": "matched",
      "output": {
        "khosla_ventures_portfolio_check": {
          "value": "Khosla Ventures led the Series B round",
          "type": "match_condition",
          "is_matched": true
        },
        "founded_after_2020_check": {
          "value": "2022",
          "type": "match_condition",
          "is_matched": true
        }
      },
      "basis": [
        {
          "field": "khosla_ventures_portfolio_check",
          "citations": [
            {
              "title": "Figure AI raises $675M",
              "url": "https://techcrunch.com/2024/02/29/figure-ai-funding/",
              "excerpts": ["Khosla Ventures led the Series B round..."]
            }
          ],
          "reasoning": "Figure AI is backed by Khosla Ventures as confirmed by multiple funding announcements.",
          "confidence": "high"
        },
        {
          "field": "founded_after_2020_check",
          "citations": [
            {
              "title": "Figure AI - Company Profile",
              "url": "https://www.figure.ai/about",
              "excerpts": ["Founded in 2022 to build general purpose humanoid robots..."]
            }
          ],
          "reasoning": "Multiple sources confirm that Figure AI was founded in 2022, which is after 2020.",
          "confidence": "high"
        }
      ]
    }
  ],
  "last_event_id": "642c949cfbdcf"
}

Troubleshooting

Run completed with 0 matched candidates

This typically happens when match conditions are too strict for the candidate pool. Try these fixes:

Relax match condition descriptions: The ingest endpoint may generate overly strict conditions, especially for temporal queries. Edit condition descriptions to be more inclusive before creating the run.
Use a stronger generator: preview evaluates 5–10 candidates according to match_limit, base searches broadly, core searches deeper, and pro is the most thorough. A stronger generator evaluates more candidates, increasing the chance of finding matches.
Check temporal language: Phrases like “founded after 2023” may be interpreted as “within the last year.” Use explicit ranges (e.g., “founded in 2025 or later”) for more predictable behavior.
Broaden your query: If your criteria are very specific, consider starting broad, adding enrichments, and filtering the enriched results in your application.
Start with preview: Always run with generator: "preview" first to validate your schema and see how conditions are being evaluated before committing to a full run.

Ingest generated unexpected conditions

The ingest endpoint interprets natural language heuristically. If the generated match_conditions don’t match your intent:

Modify the conditions before passing them to the create endpoint — see Customizing the ingest schema above.
Skip ingest entirely and construct your own schema directly with objective, entity_type, and match_conditions.
Use the schema endpoint on an existing run (GET /v1beta/findall/runs/{findall_id}/schema) to see what schema was used, then iterate on it.

Next Steps

Entity Search: Fast, synchronous people-and-company search for latency-sensitive workflows
Candidates: Understand candidate object structure, states, and exclusion
Generators and Pricing: Understand generator options and pricing
Preview: Test queries with 5–10 evaluated candidates before running full searches
Enrichments: Extract additional structured data for matched candidates
Extend Runs: Increase match limits without paying new fixed costs
Streaming Events: Receive real-time updates via Server-Sent Events
Webhooks: Configure HTTP callbacks for run completion and matches
API Reference: Complete endpoint documentation

Rate Limits

See Rate Limits for default quotas and how to request higher limits.

Getting started

Web Tools

Web Agents

Developer Tools

Platform Integrations

Data Integrations

Additional Resources

FindAll API Quickstart

What is FindAll?

Key Features & Use Cases

Pricing

Common Use Cases

What Happens During a Run

Quick Example

The Basic Workflow

Step 1: Ingest

Customizing the ingest schema

Step 2: Create FindAll Run

Step 3: Poll for Status

Step 4: Get Results

Troubleshooting

Next Steps

Rate Limits

​What is FindAll?

​Key Features & Use Cases

​Pricing

​Common Use Cases

​What Happens During a Run

​Quick Example

​The Basic Workflow

​Step 1: Ingest

​Customizing the ingest schema

​Step 2: Create FindAll Run

​Step 3: Poll for Status

​Step 4: Get Results

​Troubleshooting

​Next Steps

​Rate Limits

What is FindAll?

Key Features & Use Cases

Pricing

Common Use Cases

What Happens During a Run

Quick Example

The Basic Workflow

Step 1: Ingest

Customizing the ingest schema

Step 2: Create FindAll Run

Step 3: Poll for Status

Step 4: Get Results

Troubleshooting

Next Steps

Rate Limits