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.
Prerequisites: Before implementing Task API webhooks, read Webhook Setup & Verification for critical information on:
  • Recording your webhook secret
  • Verifying HMAC signatures
  • Security best practices
  • Retry policies
This guide focuses on Task API-specific webhook events and payloads.

Overview

Webhooks allow you to receive real-time notifications when your task runs complete, eliminating the need for constant polling—especially useful for long-running or research-intensive tasks.

Setup

To register a webhook for a task run, include a webhook parameter in your task run creation request:

Webhook Parameters

Event Types

Task API currently supports the following webhook event type:

Webhook Payload Structure

Each webhook payload contains:
  • timestamp: ISO 8601 timestamp of when the event occurred
  • type: Event type
  • data: Event-specific payload. For the ‘task_run.status’ event, it is the complete Task Run object

Example Payloads

Success
Failure

Security & Verification

For information on HMAC signature verification, including code examples in multiple languages, see the Webhook Setup Guide - Security & Verification section.

Retry Policy

See the Webhook Setup Guide - Retry Policy for details on webhook delivery retry configuration.

Best Practices

For webhook implementation best practices, including signature verification, handling duplicates, and async processing, see the Webhook Setup Guide - Best Practices section.