Skip to main content

​
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). Events are delivered in chronological order, each including event_id, timestamp, type, and data. Resumability: Use last_event_id query parameter to resume from any point after disconnections. The last_event_id is included in each event and in the /result endpoint response—if null, the stream starts from the beginning. Duration: Streams remain open while the run is active or until an optional timeout (seconds) is reached. A findall.status heartbeat is sent every 10 seconds to keep connections alive.

​
Accessing the Event Stream

cURL
curl -N -X GET "https://api.parallel.ai/v1beta/findall/runs/${FINDALL_ID}/events" \
  -H "x-api-key: ${PARALLEL_API_KEY}" \
  -H "Accept: text/event-stream" \
  -H "parallel-beta: findall-2025-09-10"

​
Event Types

The SSE endpoint emits the following event types:
Event TypeDescription
findall.statusHeartbeat of FindAllRun object every 10 seconds, or when Find All status changes
findall.candidate.generatedEmitted when a new candidate is discovered, before evaluation
findall.candidate.matchedEmitted when a candidate successfully matches all match conditions
findall.candidate.unmatchedEmitted when a candidate fails to match all conditions
findall.candidate.enrichedEmitted when enrichment data has been extracted for a candidate
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 Find All status changes. 
{
  "type": "findall.status",
  "timestamp":"2025-11-04T18:45:43.223633Z",
  "event_id": "641eebfb0d81f",
  "data": {
    "findall_id": "findall_40e0ab8c10754be0b7a16477abb38a2f",
    "status": {
      "status": "running",
      "is_active": true,
      "metrics": {
        "generated_candidates_count": 4,
        "matched_candidates_count": 0
      },
      "termination_reason": null
    }
  }
}
findall.candidate.* — Emitted as candidates are generated and evaluated: 
{
  "type": "findall.candidate.generated",
  "timestamp":"2025-11-04T18:46:52.952095Z",
  "event_id": "641eebe8d11af",
  "data": {
    "candidate_id": "candidate_a062dd17-d77a-4b1b-ad0e-de113e82f838",
    "name": "Adept AI",
    "url": "https://adept.ai",
    "description": "Adept AI is a company founded in 2021...",
    "match_status": "generated",
    "output": null,
    "basis": null
  }
}
  • Preview: Test queries with ~10 candidates before running full searches
  • Generators and Pricing: Understand processor options, pricing, and selectivity requirements
  • 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