Set query string parameter

The set-query-parameter policy adds, replaces value of, or deletes request query string parameter. Can be used to pass query parameters expected by the backend service which are optional or never present in the request.


Set the policy's elements and child elements in the order provided in the policy statement. To help you configure this policy, the portal provides a guided, form-based editor. Learn more about how to set or edit API Management policies.

Policy statement

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->


Name Description Required Default
exists-action Specifies what action to take when the query parameter is already specified. This attribute must have one of the following values.

- override - replaces the value of the existing parameter.
- skip - does not replace the existing query parameter value.
- append - appends the value to the existing query parameter value.
- delete - removes the query parameter from the request.

When set to override enlisting multiple entries with the same name results in the query parameter being set according to all entries (which will be listed multiple times); only listed values will be set in the result.

Policy expressions are allowed.
No override
name Specifies name of the query parameter to be set. Policy expressions are allowed. Yes N/A


Name Description Required
value Specifies the value of the query parameter to be set. For multiple query parameters with the same name, add additional value elements. Policy expressions are allowed. Yes



Set value of query parameter

<set-query-parameter name="api-key" exists-action="skip">

Set query parameter to forward context to the backend

This example shows how to apply policy at the API level to supply context information to the backend service.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">

For more information, see Policy expressions and Context variable.

Next steps

For more information about working with policies, see: