How should repeated query parameter names be represented in an HTTP URL?
Quick answer
There is no single URL convention that every API must use for multiple values under one parameter name. An endpoint might specify repeated pairs such as tag=red&tag=blue, a comma-separated value such as tag=red,blue, or another format. Check the documentation for the specific endpoint and operation, then build the request to match it rather than assuming how the server interprets the query.
The question, the details, the next step.
I need to send several values for one filter in an HTTP URL. What should the query look like?
Check the API documentation for that endpoint first. A URL does not prescribe one universal way for a server to interpret repeated query names: the query’s exact format is defined by the resource, and servers may interpret parameters in implementation-specific ways. [S1]
An endpoint might specify a format such as:
- Repeating the name:
?tag=red&tag=blue - Putting values in one parameter:
?tag=red,blue - Another documented format, such as a different parameter name or structure.
These are examples of possible contract choices, not interchangeable spellings. The endpoint’s documentation determines which one to send and what the values mean.
If I use JavaScript, does URLSearchParams support repeating a name?
Yes. In browser JavaScript, URLSearchParams.append(name, value) adds a name/value pair. Appending the same name more than once serializes it more than once—for example, foo=1&foo=4. [S2]
For example:
const params = new URLSearchParams();
params.append("tag", "red");
params.append("tag", "blue");
const query = params.toString(); // tag=red&tag=blueThis shows what the JavaScript interface serializes; it does not establish that a particular API accepts or interprets repeated tag values that way. Confirm the endpoint’s documented format before relying on it.
How can I tell which representation an endpoint expects if its documentation is unclear?
Look for the endpoint’s parameter description and request examples. Search for wording about arrays, multiple values, delimiters, or repeated keys. Make sure you are reading documentation for the same endpoint and operation you are calling; a format shown in one example does not by itself establish the rule for another.
If the docs remain ambiguous, ask the API owner or use a safe test environment if one is available. Compare a request containing two values in the candidate format with the documented or expected response. A successful response alone may not prove both values were interpreted as intended, so inspect the result and clarify the contract when possible. The general rule is that query interpretation is implementation-specific; the JavaScript example only documents how that interface serializes pairs. [S1][S2]
Can you show a practical way to record the decision so I don’t accidentally change it later?
Record the endpoint’s requirement alongside the request-building code or in your team’s API notes. For example, use placeholders until you have confirmed the contract:
Endpoint: [endpoint and operation]
Parameter: tag
Required representation: repeat the name
Example: ?tag=[value1]&tag=[value2]
Evidence: [documentation section or API-owner clarification]
Then make the request-building code match that note. If the API documentation specifies a comma-separated value instead, record that format and follow its documented escaping rules. Do not assume that commas or other separators are handled the same way by every API. Revisit the note if the endpoint contract changes.
A practical checklist
Identify the exact endpoint and operation you are calling.
Find its stated rule for multiple values, arrays, repeated names, or delimiters.
Compare the rule with an example from that same endpoint.
Build the URL using the documented representation, not a guessed convention.
If unclear, ask the API owner or test safely, then confirm that every value was recognized.
A few more useful answers
Is `?tag=red&tag=blue` always equivalent to `?tag=red,blue`?
No. They are different query strings, and an API may interpret them differently. Use the representation specified for the endpoint.
Does URLSearchParams prove that a server accepts duplicate names?
No. It documents how that browser JavaScript interface appends and serializes pairs; it does not establish how a server handles them. [S2]
What should I do if the documentation gives no answer?
Ask the API owner for the expected format or use a safe test environment if available. Verify that multiple values were actually applied rather than relying only on a successful response.
Sources
References used for this guide.
- [S1] URI query — MDN developer.mozilla.org · Checked
- [S2] URLSearchParams: append() method — MDN developer.mozilla.org · Checked