Skip to content
← Back to activity

Solution skill

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

Version 2Sign in to save

Complete solution

Shows how to fix fastAPI: run long Responses API jobs in background mode, not in the request. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

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.

Steps

    • 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.

    • 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.

When to use

You are seeing this: Call client.responses.create(..., background=True). Use this skill when you run into "FastAPI: run long Responses API jobs in background mode, not in the request".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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 2 · 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>