Understanding Sync and Async Modes#
When you use APIs, the mode you choose Synchronous (Sync) or Asynchronous (Async) can significantly affect both performance and cost. This article explains the differences between these modes, highlights why Async is superior, and shows how switching can benefit you.
What are Sync and Async Modes?#
Synchronous (Sync) Mode#
In Sync mode, your API request is processed immediately, and the result is returned within a limit of 30 seconds. Here are a few disadvantages:
API Response: You receive your results when the processing is complete.
No Job ID: There’s no
jobId
provided by job/check for further status checks.Time Limit: If processing takes longer than 30 seconds, your request will fail.
Higher Costs: Credits are calculated as:
Total Credits Used = Endpoint Credits × Number of Pages
Asynchronous (Async) Mode#
Async mode processes your request in the background, providing the option to track progress which gives you:
Immediate API Response: You receive a
jobId
and an output URL right away.Background Processing: Handles larger tasks without immediate timeouts.
Extended Time Limit: Can process tasks for up to 45 minutes, reducing timeouts.
Status Checks: Use the
jobId
to monitor progress via the job/check endpoint.Webhook Support: Supports callback to notify you when your job is done on a specified webhook URL.
Lower Cost: Credits are calculated as:
Total Credits Used = Endpoint Credits + (2 Credits × Number of "Job/Check" Calls)
Why Async Mode is Superior#
Handles Bigger Tasks Efficiently: Designed for larger files or complex tasks that exceed Sync mode’s 30-second limit, reducing failures and saving time.
More Cost-Effective: Although Async mode includes a small cost for each job/check call (2 credits per check), it often results in overall savings by minimizing failed requests and unnecessary retries.
Better Control and Transparency: The
jobId
allows you to check your job’s status, giving you more control and clear insight into the process.Fewer Timeouts and Failures: Extended time limits decrease the likelihood of failures.
Automates Workflow with Webhooks: Webhooks notify you automatically when your job is complete, reducing the need for manual checks and further saving on job/check credits.
How to Switch to Async Mode#
Modify Your API Request:
Specify that you want to use Async mode in your API call, often by setting an
async
parameter totrue
.
Receive the
jobId
and Output URL:After submitting your request, you’ll get a
jobId
and an output URL where results will be available once processing is complete.
Implement Status Checks (Optional):
Set Up Webhooks (Recommended):
Configure Webhooks & Callbacks to receive automatic notifications when your job is finished (costs 2 credits).
This reduces the need for manual status checks and saves on job/check credits.
Conclusion#
Async mode offers a superior approach for API interactions by providing efficiency, cost-effectiveness, and enhanced control. By switching from Sync to Async mode, you optimize resource usage and unlock features like webhooks and extended processing times.