cloro WebsiteAPI Get an API key
Guides › Making requests

Making requests

cloro exposes every capability through two call styles — a blocking one that hands you the answer on the same connection, and a queued one that hands you a task reference to collect later. Pick the style that matches your latency budget and workload shape.

Overview

A synchronous call keeps the HTTP connection open until cloro has finished the work and can return the complete payload in that one response. It is the most direct way to consume the API and suits interactive, one-off requests where a result is expected within your client's timeout window.

An asynchronous call instead accepts the work, replies straight away with a taskId, and runs the job on cloro's workers in the background. You then receive the finished result either by registering a webhook (the recommended path) or by polling the task until it settles. This style fits serverless runtimes with tight execution ceilings, bulk submissions, and any pipeline that should not depend on a connection staying alive for the full duration.

Choosing a mode

FieldTypeDescription
SynchronousmodeInteractive requests that must return an answer immediately and complete well inside the client timeout.
AsynchronousmodeServerless functions with short run limits, large batches, and resilient long-running jobs that shouldn't hold a connection open.
taskIdstringReference returned by asynchronous submissions; used to look up the result via webhook delivery or polling.
countrystringOptional geographic routing hint; the region you target can shift observed latency.

For small batches that still need results in hand right away, keep the synchronous mode and drive it with a pool of concurrent workers rather than moving to the queue. For genuinely large workloads, submit through the batch endpoint, which accepts up to 500 tasks in one HTTP request and validates each task on its own — a single bad entry never blocks the others — then collect the outcomes over webhooks or polling.

Response example

A synchronous call returns the finished result inline:

{
  "status": "completed",
  "mode": "sync",
  "data": {
    "provider": "chatgpt",
    "result": { }
  }
}

An asynchronous submission returns only a handle you resolve later:

{
  "status": "queued",
  "mode": "async",
  "taskId": "task_9f3a2c7e1b40",
  "webhook": null
}

Notes