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

# 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.
  - `entity_type` string, required — Type of the entity for the FindAll run.
  - `exclude_list` ExcludeCandidate[], nullable — List of entity names/IDs to exclude from results.
    - `name` string, required — Name of the entity to exclude from results.
    - `url` string, required — URL of the entity to exclude from results.
  - `generator` 'base' | 'core' | 'pro' | 'preview', required — Generator for the FindAll run.
  - `match_conditions` MatchCondition[], required — List of match conditions for the FindAll run.
    - `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.
    - `name` string, required — Name of the match condition.
  - `match_limit` integer, required — Maximum number of matches to find for this FindAll run.
  - `metadata` object, nullable — Metadata for the FindAll run.
  - `objective` string, required — Natural language objective of the FindAll run.
  - `webhook` Webhook — Webhooks for Task Runs.
    - `event_types` string[] — Event types to send the webhook notifications for.
    - `url` string, required — URL for the webhook.

## Response `200`

Successful Response

- FindAllRun — FindAll run object with status and metadata.
  - `created_at` string, nullable — Timestamp of the creation of the run, in RFC 3339 format.
  - `findall_id` string, required — ID of the FindAll run.
  - `generator` 'base' | 'core' | 'pro' | 'preview', required — Generator for the FindAll run.
  - `metadata` object, nullable — Metadata for the FindAll run.
  - `modified_at` string, nullable — Timestamp of the latest modification to the FindAll run result, in RFC 3339 format.
  - `status` FindAllRunStatus, required — Status object for 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.
    - `status` 'queued' | 'action_required' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required — Status of the FindAll run.
    - `termination_reason` string, nullable — Reason for termination when FindAll run is in terminal status.

## Other responses

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

## Changes

- **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/70ca78f3dbac/schema)