> ## 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.

# FindAll API Quickstart

> Discover and enrich entities from the web using natural language queries with the FindAll API

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. On `/v1/search`, `search_queries` is required (at least one short keyword query), and `max_results`, `source_policy` and `fetch_policy` go inside `advanced_settings`; sending only `objective`, or sending those fields at the top level, returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

If you are evaluating Parallel Search or comparing it with other search APIs, read [How to Eval Parallel Search](https://docs.parallel.ai/search/evaluating-search.md) before you build the harness, especially its [Common pitfalls](https://docs.parallel.ai/search/evaluating-search.md#common-pitfalls) section. The most common mistake is sending the raw question as both `objective` and the only entry in `search_queries`. Write a goal-style `objective` and 1-3 short keyword queries instead.

> [!NOTE]
>
> **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.

> [!TIP]
>
> **Need results in seconds?** [Entity Search](https://docs.parallel.ai/findall-api/entity-search.md) 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

> [!NOTE]
>
> See [Pricing](https://docs.parallel.ai/getting-started/pricing.md) 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:

1. **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.

2. **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.

3. **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:

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

```text theme={"system"}
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:**

```bash cURL theme={"system"}
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"
  }'
```

```python Python theme={"system"}
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"
)
```

```typescript TypeScript theme={"system"}
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:**

```json theme={"system"}
{
  "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.

> [!TIP]
>
> 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](https://docs.parallel.ai/findall-api/core-concepts/findall-generator-pricing.md))
* `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:**

```bash cURL theme={"system"}
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
  }'
```

```python Python theme={"system"}
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
)
```

```typescript TypeScript theme={"system"}
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:**

```json theme={"system"}
{
  "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:**

```bash cURL theme={"system"}
curl -X GET "https://api.parallel.ai/v1beta/findall/runs/findall_40e0ab8c10754be0b7a16477abb38a2f" \
  -H "x-api-key: $PARALLEL_API_KEY"
```

```python Python theme={"system"}
from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

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

```typescript TypeScript theme={"system"}
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:**

```json theme={"system"}
{
  "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.

> [!NOTE]
>
> To understand the complete candidate object structure, see [Candidates](https://docs.parallel.ai/findall-api/core-concepts/findall-candidates.md).

**Request:**

```bash cURL theme={"system"}
curl -X GET "https://api.parallel.ai/v1beta/findall/runs/findall_40e0ab8c10754be0b7a16477abb38a2f/result" \
  -H "x-api-key: $PARALLEL_API_KEY"
```

```python Python theme={"system"}
from parallel import Parallel

client = Parallel(api_key="YOUR_API_KEY")

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

```typescript TypeScript theme={"system"}
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.

```json [expandable] theme={"system"}
{
  "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

> [accordion] Run completed with 0 matched candidates
>
> This typically happens when match conditions are too strict for the candidate pool. Try these fixes:
>
> 1. **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.
> 2. **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.
> 3. **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.
> 4. **Broaden your query**: If your criteria are very specific, consider starting broad, adding [enrichments](https://docs.parallel.ai/findall-api/features/findall-enrich.md), and filtering the enriched results in your application.
> 5. **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.

> [accordion] Ingest generated unexpected conditions
>
> The ingest endpoint interprets natural language heuristically. If the generated `match_conditions` don't match your intent:
>
> 1. **Modify the conditions** before passing them to the create endpoint — see [Customizing the ingest schema](#customizing-the-ingest-schema) above.
> 2. **Skip ingest entirely** and construct your own schema directly with `objective`, `entity_type`, and `match_conditions`.
> 3. **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](https://docs.parallel.ai/findall-api/entity-search.md)**: Fast, synchronous people-and-company search for latency-sensitive workflows
* **[Candidates](https://docs.parallel.ai/findall-api/core-concepts/findall-candidates.md)**: Understand candidate object structure, states, and exclusion
* **[Generators and Pricing](https://docs.parallel.ai/findall-api/core-concepts/findall-generator-pricing.md)**: Understand generator options and pricing
* **[Preview](https://docs.parallel.ai/findall-api/features/findall-preview.md)**: Test queries with 5–10 evaluated candidates before running full searches
* **[Enrichments](https://docs.parallel.ai/findall-api/features/findall-enrich.md)**: Extract additional structured data for matched candidates
* **[Extend Runs](https://docs.parallel.ai/findall-api/features/findall-extend.md)**: Increase match limits without paying new fixed costs
* **[Streaming Events](https://docs.parallel.ai/findall-api/features/findall-sse.md)**: Receive real-time updates via Server-Sent Events
* **[Webhooks](https://docs.parallel.ai/findall-api/features/findall-webhook.md)**: Configure HTTP callbacks for run completion and matches
* **[API Reference](https://docs.parallel.ai/api-reference/findall/create-findall-run.md)**: Complete endpoint documentation

## Rate Limits

See [Rate Limits](https://docs.parallel.ai/getting-started/rate-limits.md) for default quotas and how to request higher limits.
