How It Works
Deep research jobs run asynchronously and typically take 5-10 minutes to complete. The workflow is:- Create a job — Submit a research query via POST /ai/v1/deep-research
- Poll for status — Check progress via GET /ai/v1/deep-research/ until status is
completed - Retrieve the report — The completed response includes the full markdown report and cited sources
Job Statuses
| Status | Description |
|---|---|
queued | Job is waiting to be processed |
in_progress | Research generation is underway |
completed | Report is ready — check the output field |
failed | Job failed — check the error field |
cancelled | Job was cancelled via the cancel endpoint |
Endpoints
- Create Deep Research Job — Start a new research report
- List Deep Research Jobs — View your research jobs with pagination and status filtering
- Get Deep Research Job — Poll for status and retrieve completed reports
- Cancel Deep Research Job — Cancel a queued or in-progress job
Follow-up Research
You can iteratively refine a report by passing the originaljob_id in a subsequent create request. This sends a follow-up message to the same research conversation, allowing you to ask clarifying questions or request additional analysis on the same topic.