Background tasks

Some work is too slow to finish before returning. Processing a URL, embedding a document, running a long index build. You want to acknowledge the request fast and let the work finish afterward. FastAPI ships BackgroundTasks for exactly this.

router.py
python
from fastapi import APIRouter, BackgroundTasks
from models import URLRequest
from service import process_url_background, processing_status

@router.post("/add-url")
async def add_url(request: URLRequest, background_tasks: BackgroundTasks):
    url_str = str(request.url)
    if url_str not in processing_status:
        processing_status[url_str] = {
            "url": url_str,
            "status": "processing",
            "progress": 0,
            "message": "Queued for processing...",
            "documents_count": 0,
        }
        background_tasks.add_task(
            process_url_background,
            url_str,
            request.chunk_size,
            request.chunk_overlap,
        )
    return {"message": f"Started processing URL: {url_str}", "url": url_str, "status": "processing"}

background_tasks is another type-hinted parameter FastAPI fills in. The handler returns immediately with a status message, and the task runs after the response is sent.

Two rules for BackgroundTasks. First, it runs after the response is delivered, not in parallel with it. If you need true parallelism, you want Celery or an async queue, not this. Second, exceptions inside the task do not roll back the response. Log them and persist failure state somewhere your client can poll, like the processing_status dict we wrote to up top.

Quiz: Quiz

Loading practice…

Checkpoint: Lifespan and dependencies checkpoint

Loading practice…