# Query Parameters

Serverless query parameters are the key-value pairs that appear after `?` in a request URL, such as `/api/users?status=active&page=2`. In Serverless API Gateway, they are part of the public API contract: the gateway can forward them unchanged, add new values, or map verified data such as JWT claims into the upstream request.

If you searched for `serverless query parameters`, the short answer is: Serverless API Gateway treats query parameters as request inputs that can be preserved, validated by your upstream, or rewritten through `mapping.query` before the request leaves the Cloudflare Worker.

## What Query Parameters Are

Query parameters are URL values that let a client send extra request context without changing the path. Common examples include:

* Filtering: `/api/users?status=active`
* Pagination: `/api/users?page=2&limit=20`
* Sorting: `/api/orders?sort=created_at`
* Gateway-controlled values: `/api/reports?tenant_id=acme`

They are still standard HTTP query strings. "Serverless" only changes where they are processed: a Worker or gateway handles them at the edge instead of a traditional origin server.

## How Serverless API Gateway Uses Query Parameters

With Serverless API Gateway, query parameters are useful for:

* Passing filters, pagination values, and sort options to an upstream API.
* Adding gateway-owned values before proxying a request.
* Combining path variables, JWT claims, environment variables, and static config into one upstream request shape.
* Keeping upstream services smaller by centralizing request shaping at the edge.

### Default behavior

If a route proxies to an upstream service and you do not add query mappings, the incoming query string is forwarded as part of the request URL.

Example client request:

```
GET /api/users?status=active&page=2
```

The gateway can forward `status=active&page=2` unchanged to the configured upstream.

### Query mapping behavior

When you need the gateway to add or rewrite values, use `mapping.query`.

```json
{
  "method": "GET",
  "path": "/api/v1/users",
  "integration": {
    "type": "http_proxy",
    "server": "users-api"
  },
  "auth": true,
  "mapping": {
    "query": {
      "tenant_id": "$request.jwt.tenantId",
      "region": "$config.defaultRegion",
      "requested_by": "$request.query.user"
    }
  },
  "variables": {
    "defaultRegion": "us-east-1"
  }
}
```

In that example:

* `tenant_id` comes from a verified JWT claim.
* `region` comes from route config.
* `requested_by` is copied from an incoming query parameter.

This lets the public API stay small while the upstream receives the values it actually needs.

## Common Serverless Query Parameter Patterns

### Pagination and filtering

```
/api/users?status=active&page=2
```

Use query parameters when the client should control result windows, filter conditions, or sort order.

### Tenant or user context injection

```
/api/reports?range=30d
```

The client sends only business input. The gateway injects `tenant_id`, `workspace_id`, or `user_id` from the JWT before proxying the request.

### Backward-compatible request shaping

If an upstream expects `user` but your public API exposes `userId`, the gateway can map one to the other without changing the client-facing path design.

## Security Guidance

Do not place secrets, access tokens, refresh tokens, or personally sensitive values in query parameters. URLs are commonly stored in browser history, proxy logs, analytics tools, and screenshots. Use headers or request bodies for sensitive values.

Treat query parameters as untrusted input unless the gateway derives them from JWT claims, config variables, or environment-backed values. If a parameter changes authorization or tenant scope, prefer mapping it from verified data instead of trusting the client.

## When Not to Use Query Parameters

Avoid query parameters when:

* The value is sensitive.
* The request body is a better fit, such as for large search payloads.
* The value is part of the resource identity and belongs in the path.
* The upstream should not allow clients to override it directly.

## Related Serverless API Gateway Docs

* [Variable Mapping](/configuration/variable-mapping.md) -- map request query values, JWT claims, and config variables.
* [Priority Variables](/configuration/priority-variables.md) -- understand which variable source wins when values overlap.
* [Paths](/configuration/paths.md) -- configure the routes where query strings are accepted.
* [Configuration Overview](/configuration/overview.md) -- see how query handling fits into the full gateway config.

In Serverless API Gateway, query parameters are not just URL details. They are part of the gateway contract. Forward them intentionally, map them when needed, and never use them for secrets.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serverlessapigateway.com/glossary/q/query-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.