Introduction

In Flask, query-string values are available through request.args. That object is an immutable multi-dict built from the part of the URL after the ?, so it is the standard way to read parameters such as page=2 or sort=name inside a route.

Basic Access with request.args

The simplest route reads a parameter with get:

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/search")
6def search():
7    query = request.args.get("q")
8    return {"query": query}

A request such as /search?q=flask returns the value associated with q.

request.args is preferred because it handles URL decoding and presents the parameters in a Flask-friendly structure.

Use Defaults and Type Conversion

get becomes more useful when you supply a default value or a type conversion.

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/items")
6def items():
7    page = request.args.get("page", default=1, type=int)
8    per_page = request.args.get("per_page", default=20, type=int)
9    return {"page": page, "per_page": per_page}

Now /items?page=3&per_page=50 produces integers instead of raw strings, and missing parameters fall back to sensible defaults.

This is cleaner than manually converting values after retrieval.

Query Strings Are Always Strings at the HTTP Level

It is important to remember that query parameters arrive as text. Flask can convert them for you if you use the type argument, but the raw transport format is still string-based.

For example:

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/debug")
6def debug():
7    raw_value = request.args.get("page")
8    return {"value": raw_value, "python_type": type(raw_value).__name__}

If you call /debug?page=10, the raw value is still a string unless you explicitly request conversion.

Multiple Values for the Same Key

Because request.args is a multi-dict, the same key can appear more than once in the URL. Use getlist when you expect repeated keys.

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/filter")
6def filter_items():
7    tags = request.args.getlist("tag")
8    return {"tags": tags}

A request like /filter?tag=python&tag=flask&tag=api returns all three values.

If you used plain get, you would get only one of them rather than the full list.

Access the Entire Query Mapping

Sometimes you want to inspect every parameter rather than individual ones. You can convert the multi-dict to a normal dictionary for simple one-value cases:

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/inspect")
6def inspect_query():
7    params = request.args.to_dict()
8    return params

If repeated keys matter, use the flat option carefully or keep the multi-dict structure. to_dict() by default is best when each key is expected only once.

Query Strings vs Route Parameters

Flask also supports path variables such as /users/<user_id>, which are different from query strings.

Example with both:

1from flask import Flask, request
2
3app = Flask(__name__)
4
5@app.route("/users/<int:user_id>")
6def get_user(user_id):
7    verbose = request.args.get("verbose", default="false")
8    return {"user_id": user_id, "verbose": verbose}

For /users/42?verbose=true, the user_id comes from the route path and verbose comes from the query string. Keeping that distinction clear makes route handlers much easier to reason about.

Validate Input Explicitly

Even though Flask makes access easy, query parameters are still user input. Validate them before using them in database queries, business logic, or pagination calculations.

A small defensive pattern:

1from flask import Flask, request, abort
2
3app = Flask(__name__)
4
5@app.route("/products")
6def products():
7    page = request.args.get("page", default=1, type=int)
8    if page < 1:
9        abort(400, description="page must be positive")
10    return {"page": page}

The API for reading the query string is simple. The responsibility for validating meaning still belongs to your application.

Common Pitfalls

The most common mistake is forgetting that query-string values arrive as strings and then using them numerically without conversion. Another is using get when the same parameter can appear multiple times and getlist is the correct API. Developers also sometimes confuse query-string parameters with route path variables, which leads to looking in the wrong place for data. A final issue is treating query parameters as trusted input and skipping validation because Flask already parsed them.

Summary

• In Flask, query-string parameters are read from request.args.
• Use get for a single value and getlist for repeated keys.
• Defaults and type conversion can be handled directly in get.
• Query parameters are separate from route path variables.
• Treat query-string values as user input and validate them before use.