Batch or real-time? Choosing a mode
Every FluentC request is either real-time or batch. A short guide to which fits which job, how the plans map to modes, and how to poll a batch job without waiting forever.
By FluentC2 min read
Every translation request picks a mode. It's the first decision you make, and it's easy to get wrong in both directions: batching something a person is waiting on, or running a 40,000-row catalog through real-time one string at a time.
The one question
Is someone waiting for the answer?
- Yes: use
real-time. The translation comes back in the response. - No: use
batch. The response is ajob_id, you fetch the result when it's ready.
That covers most cases.
| Job | Mode |
|---|---|
| An agent replying to a customer | Real-time |
| A chat message shown in the user's language | Real-time |
| A tool call inside an agent loop | Real-time |
| A product catalog | Batch |
| UI strings in a CI job | Batch |
| A help center, or a newsletter | Batch |
| A nightly export of order notes | Batch |
Real-time
curl -X POST https://api.fluentc.ai/ai_agent/translate \
-H "Authorization: $FLUENTC_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "Free returns within 30 days.",
"input_format": "text",
"target_language": "fr",
"mode": "real-time"
}'
You get status, translation and a token_count back in the same response. Text that FluentC has translated before comes back from memory.
Batch
curl -X POST https://api.fluentc.ai/ai_agent/translate \
-H "Authorization: $FLUENTC_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": { "title": "Wireless headphones", "cta": "Add to cart" },
"input_format": "json",
"target_language": "de",
"mode": "batch"
}'
You get a job_id. A batch request can carry up to 50,000 rows. JSON is walked, every string is translated on its own, and the structure is put back together for you.
Then ask for the result:
curl -X POST https://api.fluentc.ai/ai_agent/results \
-H "Authorization: $FLUENTC_KEY" \
-H "Content-Type: application/json" \
-d '{ "job_id": "abc123def456" }'
The status is processing, complete or failed. For JSON input, the translation in the response is a JSON-encoded string, so parse it.
Polling without waiting forever
- Wait at least five seconds between polls, or
estimated_wait_secondsif it's longer. - Cap the number of attempts. A
job_idthat doesn't exist, or one you mistyped, is reported asprocessing, not as an error. Without a cap, a wrong ID polls forever. - Resubmitting is safe. Job IDs are deterministic, so the same text and target language always produce the same
job_id.
The batch results page has a complete polling loop.
Your plan decides which modes work
| Plan | Batch | Real-time |
|---|---|---|
| Batch | Yes | No |
| Real-time | Yes | Yes |
A real-time request on a Batch plan key fails with a 422. If you see Realtime translation is not supported for this agent., that's why. See pricing for what each plan includes.
Both modes use translation memory
The memory key is built from the target language and the exact text. The mode isn't part of it. So a sentence you've already translated is answered from memory rather than translated again, and a given sentence gets the same translation whichever mode asks for it. That makes it practical to pre-translate the sentences your agents say most often in a batch, then let the agents call real-time for the rest.
See ten agents, one translation for why this matters when many agents are involved.
A rule of thumb
Start with real-time for anything interactive, and batch for anything you can run in the background. If you're unsure, ask whether you'd be comfortable showing a loading state. If yes, batch will do. If no, use real-time.
Get an API key and try both on the same sentence. The concepts page covers formats, language codes and memory in more detail.