Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 50 ยท Request parameters

Query parameters

Use FastAPI query parameters for filters and paging: defaults, optional values, bool conversion, lists, Query() validation, aliases and pagination.

The part of a URL after the question mark is the query string: /books?genre=sci-fi&limit=10. It carries optional settings such as filters, sort order and page size. In FastAPI, any function parameter that does not appear in the path is treated as a query parameter, and the type hint converts and validates it, just as with path parameters.

The difference in spirit: path parameters say which resource, query parameters say how you want it. That is why query parameters usually have defaults.

Defaults make parameters optional

A parameter with a default value is optional. One without a default is required.

Python Required, default and optional

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.

Here q has no default, so omitting it gives a 422 with the type missing and the location ["query", "q"]. limit defaults to 10. genre is typed str | None with default None, the standard way to say "optional, and absent means nothing was asked for". Your code can test if genre is not None.

Query values are text. ?limit=3 arrives as the string "3" and is converted because you wrote int. A value that cannot be converted gives a 422 with loc of ["query", "limit"].

Booleans

For bool parameters FastAPI accepts several spellings, so clients do not need to guess:

Python Which values count as True?

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.

true, 1, on, yes (and t, y) are true; false, 0, off, no are false, in any letter case. Anything else is a 422. Notice that we passed params={...}: the client builds and escapes the query string for you, which is safer than gluing strings together.

Lists of values

To accept the same key several times, as in ?tag=python&tag=api, declare a list and wrap it in Query(). Without Query() FastAPI would assume a list is a request body.

Python Repeated query parameters

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.

A list as default is safe here. FastAPI copies the default for each request, so the usual "mutable default argument" bug does not bite. Still, many teams prefer None as the default and treat it as "no filter" to make that intent explicit.

Validating with Query()

Query() adds rules and documentation. Put it inside Annotated after the type:

Argument Applies to Meaning
min_length, max_length text length limits
pattern text must match a regular expression
ge, gt, le, lt numbers range limits
alias any the name used in the URL
description, title any shown in the documentation
deprecated any marks the parameter as going away
Python Constraints, pattern and alias

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.

Study the results. A too-short q is rejected with a length message; a SKU that does not match the pattern says so; a price above the limit says "less than or equal to 1000".

The alias matters because Python names cannot contain a hyphen. The URL uses max-price while your code uses max_price. The last call shows the consequence: once an alias is set, the original name max_price is ignored, so the constraint is skipped and the default is used silently. Choose one public name and stick to it.

Pagination parameters

Almost every list endpoint needs paging. The simplest form uses skip and limit, or page and size. Constraints protect your server from absurd requests such as limit=1000000.

Python A paginated list

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.

A page past the end returns an empty list, which is a normal and useful answer. Including total lets a client draw page links. We return to paging, including keyset pagination for large tables, in CRUD, filtering and pagination.

Mixing path and query parameters

FastAPI tells the two apart by looking at the path string. A name inside braces is a path parameter; any other simple-typed name is a query parameter. You can freely combine them:

Python
@app.get("/authors/{author_id}/books")
async def books_by_author(author_id: int, genre: str | None = None, limit: int = 10):
    ...

Here author_id comes from the path and the others from the query string. There is no need to mark which is which.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In async def f(q: str, limit: int = 10), which query parameters are required?

    A parameter without a default value is required. limit has a default, so clients may leave it out.
  2. 2. How do you accept ?tag=a&tag=b as a list of strings?

    Query() tells FastAPI the list comes from repeated query parameters. Without it, a list would be read from the request body.
  3. 3. Which value does NOT convert to a bool query parameter?

    true/1/on/yes and false/0/off/no are accepted. Anything else, such as maybe, gives a 422 error.
  4. 4. A parameter is declared with Query(alias="max-price"). What happens if a client sends ?max_price=5?

    With an alias, only the alias name is looked up. The original Python name is not read, so the default value applies.
  5. 5. Why add le=10 to a page-size parameter?

    An upper limit stops clients from asking for enormous pages that would be slow or expensive.

Summary

  • Function parameters that are not in the path are query parameters.
  • No default means required; None or another default means optional.
  • bool accepts true/false, 1/0, on/off and yes/no; invalid text gives 422.
  • Use Annotated[list[str], Query()] for repeated keys.
  • Query() adds length, pattern, range, alias and documentation settings.
  • Constrain pagination parameters (ge, le) to keep your API safe.

Next, send structured data to the server in Request bodies.