Skip to main content
For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at 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 before you build the harness, especially its 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.

Overview

The /v1beta/findall/runs/{findall_id}/events endpoint provides real-time updates on candidates as they are discovered and evaluated using Server-Sent Events (SSE). Run, candidate, and schema events are delivered in chronological order with event_id, timestamp, type, and data. Error events instead contain type and error. Resumability: Use the last_event_id query parameter to resume after disconnections. Each run, candidate, or schema event has an event_id. The /result endpoint returns the ID of the latest persisted event as last_event_id; heartbeat status events are generated in memory and are not used for that result cursor. If no ID is supplied, the stream starts from the beginning. Duration: Streams remain open while the run is active or until an optional timeout is reached. timeout is measured in seconds and must be between 0 and 6,000, inclusive. A findall.status heartbeat is sent every 10 seconds to keep connections alive.

Accessing the Event Stream

Event Types

The SSE endpoint emits the following event types:
For a complete guide to candidate object structure, states, and fields, see Candidates.

Event Payloads

findall.status — Heartbeat of FindAllRun object every 10 seconds, or when FindAll status changes.
findall.candidate.* — Emitted as candidates are generated and evaluated:
  • Preview: Test queries with 5–10 evaluated candidates before running full searches
  • Generators and Pricing: Understand generator options and pricing
  • Enrichments: Extract additional structured data for matched candidates
  • Extend Runs: Increase match limits without paying new fixed costs
  • Webhooks: Configure HTTP callbacks for run completion and matches
  • Run Lifecycle: Understand run statuses and how to cancel runs
  • API Reference: Complete endpoint documentation