Some requests take a long time, for example when a model thinks thoroughly or writes a long text. Instead of keeping the connection open the whole time, you start them as a background job through the /responses endpoint. You immediately get an ID back and fetch the result as soon as it's ready, by polling, by stream or by webhook.
The /responses endpoint
POST /v1/responses is the alternative to Chat Completions in the format of OpenAI's Responses API. Instead of messages, you send input, either as plain text or as a list of messages. You'll find the response text in output[].content[] with type: "output_text", and the OpenAI libraries provide output_text for this directly.
Without further options, the endpoint responds synchronously, like Chat Completions. With stream: true, the events come as a stream. With background: true, the job runs in the background.
Start a background job
curl https://api.flowmodels.one/v1/responses \
-H "Authorization: Bearer at_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quote-2026-117-draft" \
-d '{"model": "groq/openai/gpt-oss-120b", "background": true, "input": "Write a detailed quote text for a website with an online shop."}'
The API responds immediately with HTTP 202 and an object with status: "queued":
{"id": "resp_018f1234-5678-7abc-9def-0123456789ab", "object": "response", "status": "queued", "store": true, "output": [], "output_text": ""}
Background jobs are always stored. The API rejects background: true together with store: false.
Poll the status
Use GET /v1/responses/{id} to check the state. status goes through these values:
queued: waiting for processingin_progress: currently runningcompleted: finished, the result is inoutputfailed: failed, details inerrorcancelled: cancelledincomplete: ended early, for example because the output limit was reached
Poll at sensible intervals, such as every few seconds. Each poll counts toward your request limit.
Follow the progress as a stream and resume it
If you combine background: true with stream: true, you get the events right away as a stream, and the job still runs on our side. Each event carries a running sequence_number. Remember the last one you received.
If the connection drops, the job simply keeps running. You resume the stream at the last position:
curl -N "https://api.flowmodels.one/v1/responses/resp_018f1234-5678-7abc-9def-0123456789ab?stream=true&starting_after=41" \
-H "Authorization: Bearer at_your_key" \
-H "Accept: text/event-stream"
You then get only the events after number 41. This fetch doesn't start a new model call and costs nothing extra. starting_after is a whole number from 0 and only works together with stream=true.
Result by webhook instead of polling
Instead of checking regularly, your server can be notified. To do this, create a webhook with the events response.completed, response.failed, response.cancelled and response.incomplete, see Set up FlowModels webhooks. Send its UUID at the start as webhook_endpoint_id. The delivery contains only the ID and status, and you then fetch the result with GET /responses/{id}. Verify the webhook signature explains how to secure the delivery.
Cancel
POST /v1/responses/{id}/cancel cancels a running job and returns its current state. If the job is already finished, failed or cancelled, the call still succeeds and changes nothing. So you can safely send it several times. Costs already incurred remain.
How long the result is available
You can fetch stored responses and their events for 24 hours after completion. After that, for responses that weren't stored and for responses of another team, you get 404 response_not_found. So fetch your result promptly and store it on your side.
Good to know
- With
metadata, you can include up to 16 of your own value pairs, such as your order number. They come back with the stored response. The field isn't allowed with Chat Completions. - The Brain works here just as with Chat Completions, with
external_identifierandconversation, see Use the Brain: store and continue conversations per end user. - The stored response isn't the same as the conversation history in the Brain. After 24 hours, only the retrievable response disappears, not the conversation.
- In the Python library, you send your own fields such as
external_identifierorwebhook_endpoint_idviaextra_body, see Use the OpenAI library for Python and Node.js with FlowModels.