Making requests

cloro offers two ways to call the API: synchronous requests, where you wait for the result on the same connection, and asynchronous requests, where you submit a task and retrieve the result later via webhook or polling.

​

Synchronous requests

Synchronous endpoints return the full result in the same HTTP response. Best for time-sensitive requests that need an immediate answer and fit comfortably inside your client’s request timeout. See Synchronous requests for the request and response structure, common parameters, optional response formats, and code examples.

​

Asynchronous requests

Asynchronous endpoints accept a task, return a taskId immediately, and process the work in the background. You retrieve the result via webhook (recommended) or by polling. Best for serverless environments with short execution windows, large batches, and resilient long-running workloads. See Asynchronous requests for the two-step submit-and-fetch flow, task states, queue limits, and request prioritization.

​

When to use which

​

Common questions

​

Why are my requests slower than expected?

Request latency depends on several factors:

• Provider response time (primary factor): the upstream provider’s processing time varies based on their load (peak usage times) and geographic region
• Queue depth (async requests only): your queue depth depends on your plan’s concurrency limit (higher concurrency = faster processing) and your current queue size
• Geographic routing: requests route through region-specific infrastructure, which may differ in latency depending on the country parameter you specify.

To improve performance:

• Use sync endpoints for time-sensitive requests that need immediate results
• Use async endpoints for batch processing where you don’t need instant responses
• Upgrade your plan for higher concurrency (processes async tasks faster)

​

Can I get faster processing for high-volume workloads?

Yes, the larger the plan, the greater the concurrency assigned to it. How concurrency affects speed:

• Async requests: Higher concurrency means more tasks processed at once, reducing queue wait times
• Sync requests: You can send more simultaneous requests without hitting limits

​

What’s the best way to handle large batches of requests?

For large batches, use the batch endpoint to submit up to 500 tasks per request, combined with webhooks or polling to retrieve results: Why batch for large workloads:

• Submit up to 500 tasks in a single HTTP request, reducing overhead
• Each task is validated independently. One failure doesn’t block the rest
• No need to manage concurrency limits yourself. cloro handles queuing automatically
• Can queue up to 100,000 tasks total

For smaller batches or real-time needs use sync requests with concurrent workers if you need immediate results and have manageable batch sizes. See the concurrency guide for detailed patterns and code examples.