FastAPI background tasks for async post-response processing

<p>After handling an API request (e.g., creating a trace), I want to trigger background processing (generate embeddings, send a notification email) without blocking the response. I need this to run after the response is sent to the client.</p>

<p>Use FastAPI's <code>BackgroundTasks</code>:</p> <div class="highlight"><pre><span></span><code><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">BackgroundTasks</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">generate_embedding</span><span class="p">(</span><span class="n">trace_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span> <span class="w"> </span><span class="sd">"""Runs after the response is returned to the client."""</span> <span class="n">embedding</span> <span class="o">=</span> <span class="k">await</span> <span class="n">call_openai_embeddings</span><span class="p">(</span><span class="n">trace_id</span><span class="p">)</span> <span class="k">await</span> <span class="n">store_embedding</span><span class="p">(</span><span class="n">trace_id</span><span class="p">,</span> <span class="n">embedding</span><span class="p">)</span> <span class="nd">@router</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">'/traces'</span><span class="p">,</span> <span class="n">status_code</span><span class="o">=</span><span class="mi">201</span><span class="p">)</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_trace</span><span class="p">(</span> <span class="n">body</span><span class="p">:</span> <span class="n">TraceCreate</span><span class="p">,</span> <span class="n">background_tasks</span><span class="p">:</span> <span class="n">BackgroundTasks</span><span class="p">,</span> <span class="n">db</span><span class="p">:</span> <span class="n">DbSession</span><span class="p">,</span> <span class="p">):</span> <span class="n">trace</span> <span class="o">=</span> <span class="n">Trace</span><span class="p">(</span><span class="o">**</span><span class="n">body</span><span class="o">.</span><span class="n">model_dump</span><span class="p">())</span> <span class="n">db</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">trace</span><span class="p">)</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">refresh</span><span class="p">(</span><span class="n">trace</span><span class="p">)</span> <span class="c1"># Schedule background work AFTER commit</span> <span class="n">background_tasks</span><span class="o">.</span><span class="n">add_task</span><span class="p">(</span><span class="n">generate_embedding</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">trace</span><span class="o">.</span><span class="n">id</span><span class="p">))</span> <span class="k">return</span> <span class="n">trace</span> </code></pre></div> <p>For heavier workloads, prefer Celery or arq:</p> <div class="highlight"><pre><span></span><code><span class="c1"># arq worker task</span> <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">process_embedding</span><span class="p">(</span><span class="n">ctx</span><span class="p">,</span> <span class="n">trace_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span> <span class="k">await</span> <span class="n">generate_and_store_embedding</span><span class="p">(</span><span class="n">trace_id</span><span class="p">)</span> <span class="c1"># Enqueue from route:</span> <span class="k">await</span> <span class="n">redis</span><span class="o">.</span><span class="n">enqueue_job</span><span class="p">(</span><span class="s1">'process_embedding'</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">trace</span><span class="o">.</span><span class="n">id</span><span class="p">))</span> </code></pre></div> <p>Key points: - <code>BackgroundTasks</code> run in the same process after the response is sent - Not suitable for tasks that take &gt;30s or need retry logic — use arq/Celery - Always commit to DB before scheduling background tasks that read that data</p>