Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 50 ยท Async and concurrency

Background tasks

Use FastAPI BackgroundTasks to send emails or write logs after the response is sent, test that they ran, and learn when to switch to a task queue.

Some work does not need to finish before the client gets an answer. When a user signs up, they want to see "Welcome!" right away; the welcome email can be sent a moment later. Writing an audit log, clearing a cache, or notifying another service are the same kind of job.

FastAPI has a built-in tool for this: BackgroundTasks. You register functions during the request, FastAPI sends the response first, and then runs them. In this lesson you will use it, see exactly when tasks run, test that they ran, and learn where its limits are so you know when a real task queue is the better choice.

Adding a background task

Declare a parameter of type BackgroundTasks in your endpoint. FastAPI creates the object for you. Call add_task(function, *args, **kwargs) to register work.

Python
from fastapi import BackgroundTasks, FastAPI

app = FastAPI()

async def send_welcome(email: str):
    ...   # talk to a mail service

@app.post("/signup", status_code=202)
async def signup(email: str, tasks: BackgroundTasks):
    tasks.add_task(send_welcome, email)
    return {"status": "registered"}

The endpoint returns immediately after add_task. The function is not called until the response has been sent. Task functions may be async def (run on the event loop) or plain def (run in the thread pool), following the same rule as endpoints in async def vs def endpoints.

Respond first, work later

Request arrives Your endpoint runs.
Tasks registered add_task only stores them.
Response sent The client gets its answer.
Tasks run Now the stored functions execute.
1 / 2
sequenceDiagram
    participant C as Client
    participant A as FastAPI
    participant T as Background task
    C->>A: POST /signup
    A->>A: endpoint runs, add_task
    A-->>C: 202 response
    A->>T: run send_welcome
    T-->>A: done

The response leaves before the task starts.

Watching the order of events

The first example records what happens in a list. The endpoint registers two tasks, and each task appends a line. The in-process client waits until the whole ASGI call is finished, background work included, so after await client.post(...) we can inspect the log.

Python When do background tasks run?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The log shows the endpoint finishing first (endpoint: returning), then the tasks running in the order you added them. Both tasks are async def here; on a normal server plain def tasks work too (they run in the thread pool, which the browser runner lacks).

One detail: the real client receives the response bytes before the first task starts. The in-process client in this example only returns once everything has finished, so it cannot show you that moment, but the order in the log is the order on a real server.

Failures and tasks that need data

A background task runs after the response has already been sent, so its result cannot change that response. If a task raises an exception, the client still saw its success status; the error is logged by the server, and no later tasks are guaranteed to run. This has two consequences for how you write tasks:

  • Catch and log errors inside the task. Otherwise a failed email disappears into the server log with no retry.
  • Pass plain values, not request-scoped objects. A database session created by a dependency may already be closed when the task runs. Pass an id and open what you need inside the task, or create a fresh resource there. See Class and yield dependencies for how and when dependency cleanup happens.

Background tasks can also be added from dependencies. FastAPI hands every dependency and the endpoint the same BackgroundTasks object, which makes it easy to build reusable behavior such as "audit every write".

Python A dependency that queues an audit entry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Both tasks ran: the dependency queued the audit entry and the endpoint queued the mail, and they share one BackgroundTasks object. The /broken endpoint shows the key point about failures: the client got 200 and the normal JSON body even though the task blew up afterwards. (We passed raise_app_exceptions=False so the test client does not re-raise the task's error; a real server just logs it.)

Testing that tasks ran

Because a test client waits for the full ASGI call, testing is straightforward: call the endpoint, then assert on the side effect. Replace the real side effect with something observable, such as a list or a fake mailer, using a dependency override. That is the same pattern you have seen above with MAILS and AUDIT, and it is covered in more depth in Testing FastAPI apps.

When BackgroundTasks is not enough

BackgroundTasks is deliberately simple. It runs inside the same process as your API, which brings limits:

Limit Why it matters
Lost on crash or restart Tasks live in memory; a deploy mid-task loses them.
No retries or schedule A failure is just logged.
No result tracking You cannot ask "did task 42 finish?".
Shares the worker Long or CPU-heavy tasks slow down your API on that worker.
One process only You cannot spread the work over other machines.

When tasks must survive restarts, need retries, take minutes, or must be spread over machines, use a task queue with separate worker processes: Celery, ARQ, RQ or Dramatiq, usually backed by Redis or a message broker. The endpoint then only enqueues a job and returns, and a worker picks it up.

Python
# Read-only sketch with ARQ: not runnable in the browser
@app.post("/reports")
async def create_report(user_id: int, request: Request):
    job = await request.app.state.queue.enqueue_job("build_report", user_id)
    return {"job_id": job.job_id}

A good rule: if losing the task would be annoying, BackgroundTasks is fine; if losing it would be a bug (payments, invoices), use a queue.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does a function registered with add_task run?

    add_task only stores the function. FastAPI runs it once the response has gone out.
  2. 2. A background task raises an exception. What does the client see?

    The response is sent before the task runs, so a failing task cannot change it. Catch and log errors inside the task.
  3. 3. Which job should use a real task queue like Celery or ARQ instead of BackgroundTasks?

    Tasks in BackgroundTasks live in the API process memory: no persistence, no retries, no result tracking.
  4. 4. Why should you avoid passing a request-scoped database session into a background task?

    Dependencies with yield clean up around the request. Pass an id and open what you need inside the task.

Summary

  • Add a BackgroundTasks parameter and call add_task(function, *args); the work runs after the response is sent, in the order added.
  • Tasks can be async def or def; dependencies and the endpoint share the same BackgroundTasks object.
  • A failing task cannot change the response: handle and log errors inside the task.
  • Pass simple values (ids, strings) rather than request-scoped resources.
  • Test by calling the endpoint and asserting on an observable side effect.
  • For retries, persistence, long jobs or many machines, use a task queue such as Celery or ARQ.

Next, send data to the client over time in Streaming, SSE and WebSockets.