Query Parameters

Serverless query parameters in Serverless API Gateway. Learn how query strings are forwarded, mapped, validated, and secured in Cloudflare Worker APIs.

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.

{
  "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 -- map request query values, JWT claims, and config variables.

• Priority Variables -- understand which variable source wins when values overlap.

• Paths -- configure the routes where query strings are accepted.

• Configuration Overview -- 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.