Overview
Wokelo APIs in the Discovery and Workflow Automation categories operate asynchronously. These operations involve deep AI research, large-scale data enrichment and multi-source synthesis, so they can take several minutes to complete. Rather than keeping your HTTP connection open for that entire duration, Wokelo uses a Submit, Check Status, Download pattern. Every async API returns areport_id as soon as the request is accepted. This ID is your handle for everything that follows. Your integration stays non-blocking: submit a job, move on, and download the results when they are ready.
Why Asynchronous?
Wokelo produces intelligence at investment-grade quality, resolving entities, deduplicating signals across sources and running structured AI workflows. This depth takes time, and a synchronous API would need to hold a connection open for the full run. The async pattern lets you:- Decouple submission from retrieval: start a job and handle the result whenever it is ready
- Handle long-running tasks reliably: no timeout failures on deep research jobs
- Run multiple requests in parallel: submit many jobs at once and track each by its
report_id - Integrate cleanly into pipelines: queue results, trigger downstream workflows, or store outputs on completion
The Three-Step Flow
Step 1: Submit a Request
Call the relevant API endpoint with your parameters. The API returns immediately with areport_id.
Example: starting a Market Map workflow
Save the report_id. You need it in Steps 2 and 3.
Step 2: Check Report Status
After submitting, periodically call the Get Report Status endpoint with yourreport_id.
Status values
Poll with a gradually increasing interval rather than a tight loop. Polling more often does not speed up results.
Polling code examples
Step 3: Download the Report
Once the status isCompleted, export the report with the Download Report endpoint. Pass the report_id and the export format in the request body.
Example: