How to Get Query Params in Next.js API Routes Easily

In Next.js API routes, you get query parameters from the req.query object inside the handler function. This object contains all URL query parameters as key-value pairs, which you can use to customize your API response.

Syntax

In a Next.js API route, the handler function receives two arguments: req (request) and res (response). The query parameters are accessed via req.query, which is an object containing all query keys and values.

For example, if the URL is /api/example?name=John&age=30, then req.query will be { name: 'John', age: '30' }.

javascript

export default function handler(req, res) {
  const queryParams = req.query;
  res.status(200).json({ queryParams });
}

Example

This example shows a Next.js API route that reads query parameters and returns them in the JSON response. Try calling /api/user?name=Alice&role=admin to see the query parameters returned.

javascript

export default function handler(req, res) {
  const { name, role } = req.query;
  res.status(200).json({ message: `User name is ${name} and role is ${role}` });
}

Output

{"message":"User name is Alice and role is admin"}

Common Pitfalls

• Missing query parameters: If you expect a query param but it is not provided, req.query will have undefined for that key. Always check if the parameter exists before using it.
• Type issues: Query parameters are always strings (or arrays of strings). Convert them to numbers or booleans if needed.
• Using req.body instead of req.query: Query params come from the URL, so they are in req.query, not req.body.

javascript

export default function handler(req, res) {
  // Wrong: trying to get query params from body
  const name = req.body.name; // This will be undefined for GET requests

  // Right: get query params from req.query
  const correctName = req.query.name || 'Guest';

  res.status(200).json({ name: correctName });
}

Quick Reference

Concept	Description	Example
Access query params	Use req.query inside API handler	const { id } = req.query;
Query param type	Always string or string array	Convert with Number(req.query.page) if needed
Missing param	Check if param exists before use	const name = req.query.name || 'default';
Request method	Query params are in URL, not body	Use req.query for GET, req.body for POST data

Key Takeaways

Access query parameters in Next.js API routes using req.query inside the handler.

Query parameters are always strings; convert types as needed before use.

Always check if query parameters exist to avoid undefined values.

Do not confuse query parameters (req.query) with request body data (req.body).