# Perplexity Async Jobs — Long Research with Webhook Callbacks

> Perplexity Async Jobs API runs deep research as background. Submit query, poll or webhook for completion. For reports and multi-step synthesis.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

1. POST `/async/chat/completions` with request body + optional webhook
2. Poll `/async/chat/completions/{id}` until status=COMPLETED — or wait for webhook
3. Verify webhook HMAC-SHA256 signature before processing

---

## Intro

Perplexity's Async Jobs API submits long-running research as a background job rather than blocking a request — perfect for `sonar-deep-research` queries that take minutes and would otherwise time out a normal HTTP connection. Poll the status endpoint or register a webhook for completion. Best for: research reports, market analyses, multi-source comparisons, anywhere you'd rather email/notify than block. Works with: REST, Python httpx, JS fetch. Setup time: 10 minutes.

---

### Submit a deep research job

```python
import httpx, os

headers = {"Authorization": f"Bearer {os.environ['PPLX_API_KEY']}"}

job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {
            "model": "sonar-deep-research",
            "messages": [{"role": "user", "content": "Comprehensive 2026 state of voice AI agents: top platforms, latency benchmarks, pricing, target use cases. 1500 words."}],
            "search_domain_filter": ["livekit.io", "vapi.ai", "retellai.com", "elevenlabs.io", "techcrunch.com", "a16z.com"],
        },
    },
).json()

print(job["id"], job["status"])    # status: "QUEUED"
```

### Poll for completion

```python
import time

while True:
    r = httpx.get(f"https://api.perplexity.ai/async/chat/completions/{job['id']}", headers=headers).json()
    if r["status"] == "COMPLETED":
        print(r["response"]["choices"][0]["message"]["content"])
        print("Citations:", r["response"]["citations"])
        break
    elif r["status"] == "FAILED":
        raise RuntimeError(r.get("failed_reason"))
    time.sleep(5)
```

### Webhook completion (preferred for prod)

```python
job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {...},
        "webhook": {"url": "https://your-app.com/perplexity/done", "secret": "shared-signing-secret"},
    },
).json()

# Resulting POST to your endpoint:
# { "job_id": "...", "status": "COMPLETED", "response": {...} }
# Verify HMAC-SHA256(body, secret) against X-Perplexity-Signature header.
```

### Status lifecycle

| Status | Meaning |
|---|---|
| QUEUED | Accepted, awaiting worker |
| IN_PROGRESS | Worker started; searching + drafting |
| COMPLETED | Done; response field populated |
| FAILED | Error; check `failed_reason` |

### When to use Async over sync

- Deep-research model with >30s expected duration → Async (sync hits 60s timeout)
- Background batch jobs (overnight reports) → Async
- User clicks 'Generate report' button and walks away → Async + webhook → email
- Real-time chat → sync sonar/sonar-pro

---

### FAQ

**Q: How long can a job run?**
A: Up to 30 minutes for deep-research. Most finish in 1-5 min. Webhook is mandatory above ~5 min unless you can keep a poll loop alive — most platforms can't reliably.

**Q: What if my webhook is down when the job completes?**
A: Perplexity retries with exponential backoff for up to ~24 hours. After that the result stays retrievable via GET on the job ID for 7 days. Build idempotency: store job_id, dedupe on retry.

**Q: Can I cancel an in-flight job?**
A: Yes — DELETE on the job endpoint. Useful when a user navigates away from a research request. No partial result is returned; charges depend on what was already searched.

---

## Source & Thanks

> Built by [Perplexity](https://github.com/perplexityai). Async API docs at [docs.perplexity.ai/api-reference/async-chat-completions-post](https://docs.perplexity.ai).
>
> REST + OpenAI-compat

---

<!-- ZH -->

## 快速使用

1. POST `/async/chat/completions` 带 request body + 可选 webhook
2. 轮询 `/async/chat/completions/{id}` 等 status=COMPLETED —— 或等 webhook
3. 处理前验 webhook 的 HMAC-SHA256 签名

---

## 简介

Perplexity 的 Async Jobs API 把长时间研究当后台任务跑而不是阻塞请求 —— 适合 `sonar-deep-research` 这种几分钟的查询（否则会让普通 HTTP 连接超时）。轮询状态 endpoint 或注册 webhook 等完成。适合研究报告、市场分析、多源比较 —— 任何宁愿邮件/通知而不愿阻塞的场景。兼容 REST、Python httpx、JS fetch。装机时间 10 分钟。

---

### 提交一个 deep research 任务

```python
import httpx, os

headers = {"Authorization": f"Bearer {os.environ['PPLX_API_KEY']}"}

job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {
            "model": "sonar-deep-research",
            "messages": [{"role": "user", "content": "2026 语音 AI agent 全景：头部平台、延迟基准、价格、目标用例。1500 字。"}],
            "search_domain_filter": ["livekit.io", "vapi.ai", "retellai.com", "elevenlabs.io", "techcrunch.com", "a16z.com"],
        },
    },
).json()

print(job["id"], job["status"])    # status: "QUEUED"
```

### 轮询等完成

```python
import time

while True:
    r = httpx.get(f"https://api.perplexity.ai/async/chat/completions/{job['id']}", headers=headers).json()
    if r["status"] == "COMPLETED":
        print(r["response"]["choices"][0]["message"]["content"])
        print("引用：", r["response"]["citations"])
        break
    elif r["status"] == "FAILED":
        raise RuntimeError(r.get("failed_reason"))
    time.sleep(5)
```

### Webhook 完成（生产首选）

```python
job = httpx.post(
    "https://api.perplexity.ai/async/chat/completions",
    headers=headers,
    json={
        "request": {...},
        "webhook": {"url": "https://your-app.com/perplexity/done", "secret": "shared-signing-secret"},
    },
).json()

# 你 endpoint 收到的 POST：
# { "job_id": "...", "status": "COMPLETED", "response": {...} }
# 用 X-Perplexity-Signature header 验 HMAC-SHA256(body, secret)。
```

### 状态生命周期

| 状态 | 含义 |
|---|---|
| QUEUED | 已接收，等 worker |
| IN_PROGRESS | Worker 起跑；搜索 + 起草 |
| COMPLETED | 完成；response 字段已填 |
| FAILED | 报错；看 `failed_reason` |

### 什么时候用 Async 而不是同步

- 预期 >30 秒的 deep-research 模型 → Async（同步打 60 秒超时）
- 后台批量任务（隔夜报告）→ Async
- 用户点「生成报告」走开 → Async + webhook → 邮件
- 实时聊天 → 同步 sonar / sonar-pro

---

### FAQ

**Q: 任务能跑多久？**
A: deep-research 最多 30 分钟。大多数 1-5 分钟完成。Webhook 在 >~5 分钟基本必备，除非你能保活轮询 loop —— 大多数平台不可靠。

**Q: 任务完成时我 webhook 挂了怎办？**
A: Perplexity 按指数退避重试最多约 24 小时。之后结果通过 GET job ID 可取，保留 7 天。做幂等：存 job_id、重试去重。

**Q: 能取消在飞的任务吗？**
A: 能 —— DELETE job endpoint。用户离开研究请求时有用。不返回部分结果；按已搜的部分计费。

---

## 来源与感谢

> Built by [Perplexity](https://github.com/perplexityai). Async API docs at [docs.perplexity.ai/api-reference/async-chat-completions-post](https://docs.perplexity.ai).
>
> REST + OpenAI-compat


---
Source: https://tokrepo.com/en/workflows/perplexity-async-jobs-long-research-with-webhook-callbacks
Author: Perplexity