Background tasks in FastAPI - Step-by-Step Execution

Concept Flow - Background tasks

Client sends HTTP request

↓

FastAPI receives request

↓

Start main request handler

↓

Schedule background task

↓

Return HTTP response immediately

↓

Background task runs separately

↓

Background task completes

FastAPI handles the request, schedules a background task to run after response, then immediately returns the response while the task runs separately.

Execution Sample

FastAPI

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open('log.txt', 'a') as f:
        f.write(message + '\n')

@app.post('/send/')
async def send_message(background_tasks: BackgroundTasks, msg: str):
    background_tasks.add_task(write_log, msg)
    return {'message': 'Message received'}

This FastAPI app schedules a background task to write a message to a file after sending the HTTP response.

Execution Table

Step	Action	Background Task Scheduled?	Response Sent	Background Task Running	Result
1	Client sends POST /send/ with msg='Hello'	No	No	No	Request received by FastAPI
2	FastAPI calls send_message handler	No	No	No	Handler starts
3	background_tasks.add_task(write_log, 'Hello') called	Yes	No	No	Task scheduled to write 'Hello' to log.txt
4	Return {'message': 'Message received'}	Yes	Yes	No	Response sent to client immediately
5	Background task write_log('Hello') starts	Yes	Yes	Yes	Writing 'Hello' to log.txt
6	Background task write_log('Hello') completes	Yes	Yes	No	Message logged in file
7	Request cycle ends	Yes	Yes	No	Background task done, request fully processed

💡 Background task runs after response sent; request cycle ends when task completes.

Variable Tracker

Variable	Start	After Step 3	After Step 4	After Step 5	Final
background_tasks	empty	contains write_log task	contains write_log task	contains write_log task (running)	empty after completion
response	none	none	{'message': 'Message received'} sent	sent	sent
log.txt content	empty	empty	empty	contains 'Hello\n'	contains 'Hello\n'

Key Moments - 3 Insights

Why does the HTTP response return before the background task finishes?

Because FastAPI schedules the background task to run after sending the response immediately (see execution_table step 4). This lets the client get a quick reply without waiting.

Is the background task blocking the main request handler?

No, the background task runs separately after the response is sent (execution_table steps 5 and 6). The main handler finishes quickly after scheduling the task.

What happens if the background task fails?

FastAPI does not retry background tasks automatically. The failure happens after response is sent, so client is unaware (not shown in this trace).

Visual Quiz - 3 Questions

Look at the execution_table, at which step is the HTTP response sent to the client?

A Step 3

B Step 4

C Step 5

D Step 6

💡 Hint

Check the 'Response Sent' column in execution_table rows.

According to variable_tracker, what is the state of 'background_tasks' after step 5?

A Empty, no tasks scheduled

B Contains write_log task, not started

C Contains write_log task, running

D Task completed and removed

💡 Hint

Look at 'background_tasks' row and 'After Step 5' column in variable_tracker.

If the background task took longer, how would the response timing change?

A Response would still be sent immediately

B Response would never be sent

C Response would be delayed until task finishes

D Background task would run before request handler

💡 Hint

Refer to concept_flow and execution_table steps 4 and 5 about response timing.

Concept Snapshot

FastAPI Background Tasks:
- Use BackgroundTasks parameter in path operation
- Call background_tasks.add_task(func, args) to schedule
- Response returns immediately
- Background task runs after response
- Useful for non-blocking work like logging or sending emails

Full Transcript

In FastAPI, background tasks let you run code after sending the HTTP response. When a client sends a request, FastAPI runs the handler function. Inside, you add a background task using background_tasks.add_task. FastAPI then immediately returns the response to the client without waiting for the task to finish. The background task runs separately, for example writing a message to a file. This keeps the app fast and responsive. The execution table shows each step: receiving request, scheduling task, sending response, running task, and completing. Variables like background_tasks and response state change accordingly. Key points are that the response is sent before the task runs, and the task does not block the main handler. This pattern is great for tasks like logging or sending emails that don't need to delay the client. The visual quiz checks understanding of when response is sent and how background tasks behave.

Practice

1. What is the main purpose of using BackgroundTasks in FastAPI?

easy

A. To handle database connections synchronously

B. To replace the main event loop in FastAPI

C. To block the request until a task finishes

D. To run code after sending the response without delaying the user

Solution

1. Step 1: Understand what BackgroundTasks do

   BackgroundTasks allow running code after the response is sent, so the user is not delayed.

2. Step 2: Compare options with this behavior

   Only To run code after sending the response without delaying the user describes running code after response without delay; others describe blocking or unrelated tasks.

3. Final Answer:

   To run code after sending the response without delaying the user -> Option D

4. Quick Check:

   BackgroundTasks run code after response = B [OK]

Hint: BackgroundTasks run after response to avoid user wait [OK]

Common Mistakes:

• Thinking BackgroundTasks block the response
• Confusing BackgroundTasks with synchronous code
• Assuming BackgroundTasks replace main event loop

2. Which of the following is the correct way to add a background task in a FastAPI endpoint?

easy

A. Import BackgroundTasks but do not use it

B. Call your_function() directly inside the endpoint

C. Use background_tasks.add_task(your_function, arg1, arg2) inside the endpoint

D. Use await your_function() inside the endpoint

Solution

1. Step 1: Recall how to add background tasks in FastAPI

   You add tasks by calling background_tasks.add_task(function, args) inside the endpoint function.

2. Step 2: Check each option

   Use background_tasks.add_task(your_function, arg1, arg2) inside the endpoint correctly uses add_task. Call your_function() directly inside the endpoint calls function immediately, blocking. Use await your_function() inside the endpoint awaits function, blocking. Import BackgroundTasks but do not use it does nothing.

3. Final Answer:

   Use background_tasks.add_task(your_function, arg1, arg2) inside the endpoint -> Option C

4. Quick Check:

   Use add_task to schedule background work = D [OK]

Hint: Use add_task method on BackgroundTasks instance [OK]

Common Mistakes:

• Calling the function directly instead of scheduling
• Awaiting the function which blocks response
• Importing BackgroundTasks but not using it

3. Given this FastAPI code snippet, what will be printed after the response is sent?

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    print(f"Log: {message}")

@app.get("/items/{item_id}")
async def read_item(item_id: int, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Item {item_id} accessed")
    return {"item_id": item_id}

medium

A. Log: Item {item_id} accessed is printed after response

B. Log: Item {item_id} accessed is printed before response

C. Nothing is printed because print is not awaited

D. SyntaxError because BackgroundTasks is not imported

Solution

1. Step 1: Understand background task behavior

   The function write_log is scheduled as a background task, so it runs after the response is sent.

2. Step 2: Analyze print timing

   Print inside write_log will execute after response, printing the log message with the item_id value.

3. Final Answer:

   Log: Item {item_id} accessed is printed after response -> Option A

4. Quick Check:

   Background task runs after response = C [OK]

Hint: Background tasks run after response, so print happens later [OK]

Common Mistakes:

• Thinking print runs before response
• Assuming print won't run without await
• Missing import of BackgroundTasks (actually imported here)

4. Identify the error in this FastAPI code using background tasks:

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(email: str):
    print(f"Sending email to {email}")

@app.post("/send")
async def send(background_tasks: BackgroundTasks, email: str):
    background_tasks.add_task(send_email)
    return {"message": "Email scheduled"}

medium

A. Missing argument when adding task to background_tasks

B. BackgroundTasks should not be a parameter

C. send_email should be async

D. Email parameter must be inside the function send_email

Solution

1. Step 1: Check how add_task is called

   The function send_email requires an argument email, but add_task is called without arguments.

2. Step 2: Identify the missing argument

   The call should be background_tasks.add_task(send_email, email) to pass the email parameter.

3. Final Answer:

   Missing argument when adding task to background_tasks -> Option A

4. Quick Check:

   add_task needs function arguments = A [OK]

Hint: Pass all function args in add_task call [OK]

Common Mistakes:

• Forgetting to pass required arguments to add_task
• Thinking BackgroundTasks can't be a parameter
• Assuming send_email must be async

5. You want to log user activity and send a welcome email after a user registers. Which is the best way to do this using FastAPI background tasks?

hard

A. Call logging and email functions directly inside the endpoint synchronously

B. Add two background tasks: one for logging, one for sending email, both added via background_tasks.add_task

C. Use await on both logging and email functions inside the endpoint

D. Run logging in background task but send email synchronously

Solution

1. Step 1: Understand the goal

   We want to run both logging and sending email after response without delaying user.

2. Step 2: Evaluate options

   Add two background tasks: one for logging, one for sending email, both added via background_tasks.add_task schedules both tasks as background tasks, so they run after response. Options B and C block response. Run logging in background task but send email synchronously delays sending email.

3. Final Answer:

   Add two background tasks: one for logging, one for sending email, both added via background_tasks.add_task -> Option B

4. Quick Check:

   Schedule all post-response tasks with add_task = A [OK]

Hint: Add all post-response jobs as background tasks [OK]

Common Mistakes:

• Running tasks synchronously blocking response
• Mixing sync and async incorrectly
• Scheduling only one task in background