FastAPI for AI Engineers - Part 10: Mastering FastAPI: Scaling with APIRouters and Background Tasks

Description and use

Modular routing with APIRouter simplifies FastAPI structure, while BackgroundTasks handle long AI operations without blocking the client.

Problem

Routing all endpoints through a single main.py file becomes unmaintainable as the project grows, leading to debugging nightmares.

Outcome

Modular routing with APIRouter reduces code complexity and improves maintainability, while BackgroundTasks decouple heavy AI processing from HTTP responses, preventing client timeouts.

Workflow

• Create routers directory and add auth.py, agents.py, tasks.py with APIRouter instances
• Define route prefixes and tags in each router
• Move endpoint definitions from main.py to respective router files using @router.get/post/etc.
• In main.py, import routers and call app.include_router for each
• Run FastAPI app and verify /docs shows organized endpoints
• Define heavy AI processing function (e.g., simulate_ai_agent) that opens a new DB session
• Inject BackgroundTasks into endpoint and add background_task(simulate_ai_agent, task_id)
• Return a JSON response with status: queued immediately
• Ensure frontend handles queued status and polls or receives updates

Evidence

routing every endpoint through a single main.py file creates an unmaintainable, thousands-of-lines-long bottleneck

Source

APIRouter as a mini-FastAPI instance. It allows you to split your endpoints across multiple files based on their domain

Source

FastAPI’s BackgroundTasks solves this by decoupling the HTTP response from the heavy computation

Source