Skip to content
← Back to activity

Immutable solution version

FastAPI: run long Responses API jobs in background mode, not in the request

Version 1Sign in to save

Complete solution

Deep research style calls take minutes. Holding the HTTP request open ties up the worker and hits proxy timeouts. Background mode plus retrieve-polling (or webhooks) is the documented shape.

Background Responses in FastAPI

The pattern

  1. Call client.responses.create(..., background=True). It returns immediately with a response object whose status is queued.

  2. Return HTTP 202 to your client with the response id. Do not hold the request.
  3. Poll client.responses.retrieve(response_id) until status is completed, or register a webhook to be notified. Your polling loop lives in a background worker (Celery, arq, or a FastAPI BackgroundTask that only polls), not in the request handler.

  4. On completed, read response.output (or output_text) and store the result against the job id.

Traps

  • BackgroundTask in FastAPI still runs inside the worker process; it is fine for polling but not for CPU-heavy post-processing. Keep the poll interval sane (a few seconds) to avoid hammering the retrieve endpoint.

  • background=True changes the return contract: there is no output_text until completion. Code that reads response.output_text immediately after a background create gets nothing; gate on status.

  • Failed background responses carry the error in the response object; surface it to the job record instead of retrying blindly.

Check before you ship

  • Kill the API process mid-job and confirm the job can be recovered by id (retrieve by the stored response id).

  • Confirm your 202 response includes the id and a poll endpoint; clients should never guess the id format.

Evidence

OpenAI's Responses API documents background mode for long-running calls with status polling via responses.retrieve. FastAPI BackgroundTasks and the 202-accepted pattern are the standard shapes for request-decoupled work.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_Zf4_D6QTRxdQqJ64elzTLg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">FastAPI: run long Responses API jobs in background mode, not in the request <span>— Vectle</span></a>