---
title: "Create FindAll Run"
method: POST
path: "/v1beta/findall/runs"
tags: ["FindAll"]
---

# Create FindAll Run

`POST /v1beta/findall/runs`

Starts a FindAll run.

This endpoint immediately returns a FindAll run object with status set to 'queued'.
You can get the run result snapshot using the GET /v1beta/findall/runs/{findall_id}/result endpoint.
You can track the progress of the run by:
- Polling the status using the GET /v1beta/findall/runs/{findall_id} endpoint,
- Subscribing to real-time updates via the /v1beta/findall/runs/{findall_id}/events
endpoint,
- Or specifying a webhook with relevant event types during run creation to receive
notifications.

## Headers

- `parallel-beta` string, nullable

## Request body

- FindAllRunInput — Input model for FindAll run.
  - `objective` string, required — Natural language objective of the FindAll run.
  - `entity_type` string, required — Type of the entity for the FindAll run.
  - `match_conditions` MatchCondition[], required — List of match conditions for the FindAll run.
    - `name` string, required — Name of the match condition.
    - `description` string, required — Detailed description of the match condition. Include as much specific information as possible to help improve the quality and accuracy of Find All run results.
  - `generator` 'base' | 'core' | 'pro' | 'preview', required — Generator for the FindAll run. One of base, core, pro, preview.
  - `match_limit` integer, required — Maximum number of matches to find for this FindAll run. Must be between 5 and 1000 (inclusive). May return fewer results.
  - `exclude_list` ExcludeCandidate[], nullable — List of entity names/IDs to exclude from results. At most 10,000 entries are allowed.
    - `name` string, required — Name of the entity to exclude from results.
    - `url` string, required — URL of the entity to exclude from results.
  - `metadata` object, nullable — Metadata for the FindAll run.
  - `webhook` Webhook — Webhooks for Task Runs.
    - `url` string, required — URL for the webhook.
    - `event_types` string[] — Event types to send the webhook notifications for.
  - `memory_scope_key` string, nullable — User-provided key identifying the memory scope to use. Omit to use personal memory, if available.

## Response `200`

Successful Response

- FindAllRun — FindAll run object with status and metadata.
  - `findall_id` string, required — ID of the FindAll run.
  - `status` FindAllRunStatus, required — Status object for FindAll run.
    - `status` 'queued' | 'action_required' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required — Status of the FindAll run.
    - `is_active` boolean, required — Whether the FindAll run is active
    - `metrics` FindAllCandidateMetrics, required — Metrics object for FindAll run.
      - `generated_candidates_count` integer — Number of candidates that were selected.
      - `matched_candidates_count` integer — Number of candidates that evaluated to matched.
    - `termination_reason` 'low_match_rate' | 'match_limit_met' | 'candidates_exhausted' | 'user_cancelled' | 'error_occurred' | 'timeout' | 'insufficient_funds', nullable — Reason for termination when FindAll run is in terminal status.
  - `generator` 'base' | 'core' | 'pro' | 'preview', required — Generator for the FindAll run.
  - `metadata` object, nullable — Metadata for the FindAll run.
  - `created_at` string, nullable — Timestamp of the creation of the run, in RFC 3339 format.
  - `modified_at` string, nullable — Timestamp of the latest modification to the FindAll run result, in RFC 3339 format.

## Other responses

- `402` — Payment required: insufficient credit in account
- `422` — Unprocessable content: request validation error
- `429` — Too many requests: quota temporarily exceeded

## Changes

> 21 revisions in range; 2 could not be searched.

- **2026-06-08** `973957d74ceb` — 1 info
  - `header` request parameter `parallel-beta` was deprecated
- **2026-04-21** `57e1c56be094` — 2 info
  - api tag `FindAll` added
  - api tag `FindAll API (Beta)` removed
- **2026-03-09** `970b780e8649` — 1 warning
  - added the new `insufficient_funds` enum value to the `status/termination_reason/anyOf[subschema #1]/` response property for the response status `200`
- **2026-01-13** `105d778ad64d` — 4 breaking, 20 info
  - the `error` response's property type/format changed from ``/`` to `object`/`` for status `402`
  - the `error` response's property type/format changed from ``/`` to `object`/`` for status `422`
  - the `error` response's property type/format changed from ``/`` to `object`/`` for status `429`
  - the `status` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - …20 more
- **2025-11-13** `70ca78f3dbac` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1beta/findall/runs/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) · [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/parallel-web/parallel-api/revisions/1595294c8795/schema)