The uploader reads two columns from your file: the address and the alias you want. Everything else — group, tags, UTM parameters — is set once for the whole batch in the form, not per row.
That is the one thing worth knowing before you assemble the file. The format, the limits and half the reasons rows later fail all follow from it.
Below: how to build a file that goes through in one piece, what to do when different links need different parameters, how many rows go at a time, and how to read the report when some links don't get created.
What file the uploader accepts
A CSV or a plain text file will do. Parsing is forgiving, and a few details will save you some fiddling.
The delimiter is detected automatically. The uploader looks at the first line and picks whichever of comma, semicolon or tab occurs most often. That matters because Excel in any locale that uses the comma as a decimal separator exports CSV with semicolons, and such a file needs no rework. A comma-separated export from Google Sheets works just as well, and so does a column copied straight out of a spreadsheet, which arrives tab-separated.
A header row is optional. If the first line starts with url, alias or link, it is treated as a header and left out of the batch. With no header, the first column is the address and the second is the alias.
One column is fine. A list of addresses, one per line, with no delimiters at all, is accepted as it is.
url,alias
https://example.com/catalog/sale/shoes-2026,shoes
https://example.com/catalog/sale/bags-2026,bags
https://example.com/catalog/sale/coats-2026
An address containing a comma has to be quoted. This is ordinary CSV behaviour, but it is exactly where exports with parameters trip up:
"https://example.com/search?tags=sale,new",sale-new
Without the quotes the row splits on that comma and a fragment of the address lands in the alias. A doubled quote inside a value ("") means a literal quote — again, standard CSV.
Blank lines are skipped, so there is no need to clean trailing newlines out of the file.
Aliases can be left empty selectively: the third link in the example above has none, and a code will be generated for it. Mixing rows with and without an alias is allowed.
When different links need different parameters
Group, tags and UTM parameters apply to the entire batch at once. Convenient when you are uploading one catalogue or one mailing; a constraint as soon as the list spans several campaigns.
Two workarounds that hold up.
Build the parameters into the addresses. UTM tags are ordinary query parameters, so they can differ per row if you append them in the addresses themselves:
url
https://example.com/a?utm_source=newsletter&utm_campaign=june
https://example.com/b?utm_source=telegram&utm_campaign=june
Assembling that column in a spreadsheet takes one concatenation formula. If you are unsure which parameters to use and in what form, there is a separate breakdown of UTM parameters.
Split into several batches. One batch per campaign: each gets its own tags and its own group, and afterwards you can read statistics by group instead of picking apart one long list. This route is usually cleaner when there are only a few campaigns.
How many links go at a time
There are three limits, and they are different in kind.
| How many | |
|---|---|
| Rows in one upload | 1,000 |
| Concurrent uploads | 3 |
| Links in one API request | 100 |
If the file holds more than a thousand rows, split it: rows beyond the limit simply will not make it into the upload. Three concurrent uploads is a ceiling on unfinished jobs, not a daily quota — as soon as one finishes, you can start the next.
The monthly volume is a separate matter and depends on the plan. Bulk shortening is not available on the free plan at all. Pro allows 100 links a month, which is enough to try it on a real list and find out whether you need the volume. Premium has no monthly cap, but a daily ceiling of 30,000 links applies.
Why some rows don't get created
One bad row does not cancel the batch. The upload runs to the end, and each row carries its own outcome. There are three statuses, and telling them apart is useful because the fixes differ.
Rejected at validation. The row failed checks, and you see this right after the file is parsed, before any shortening happens. Usually a malformed address, an over-long alias, or junk where a URL should be.
Not created. The row was valid, but the link did not happen — for instance, the requested alias was already taken.
Created. Done; the short link sits next to the row.
Typical causes and what to do about them:
| What you see | What's going on | What to do |
|---|---|---|
| Row rejected, address looks fine | no scheme — example.com instead of https://example.com |
prepend https:// with a formula down the column |
| Every other row rejected | addresses with commas were not quoted | quote the values, or save the file with semicolons |
| A fragment of the link ended up in the alias | same cause: the row split on the delimiter | same fix |
| Alias truncated | alias longer than allowed | shorten to 10 characters |
| Not created, alias taken | that code already exists | change the alias or leave the field empty |
| Fewer rows loaded than the file holds | file has more than 1,000 rows | split the file |
A habit worth forming: run the first ten rows of the file through before the rest. A systematic problem with the export — wrong scheme, wrong delimiter, an extra column — shows up on ten rows exactly as it would on a thousand, and is far quicker to untangle.
If the list is produced by code
When links are prepared by your software rather than by a person with a spreadsheet, there is a batch API method: up to 100 links in one request, with a per-item response carrying the same split into created, not created and rejected.
There is a non-obvious detail here that is easy to hit. A batch spends rate limit per link, not as a single request. A batch of 100 links consumes 100 units. Otherwise the batch method would become a way around the rate limit, and one client could create thousands of links a minute. If the remaining limit does not cover the whole batch, the request is rejected outright and nothing is created — so check the remainder before sending, not after.
Shared parameters work the same way as in the form: the defaults block is merged into every row, and a row's own fields override it. An empty value in a row means "not specified", so the value comes from defaults, exactly like an empty cell in an export. The endpoint and the response schema are described in the API documentation.
What to do with the finished list
Short links from a batch are no different from ones created individually: each has its own click statistics, geography and sources. If you set a shared group on the batch, reading statistics by that group is convenient — it shows how the whole catalogue or the whole mailing performed as a unit.
Two steps that pay off specifically on large lists:
- your own domain. Across a batch of a thousand links the domain name meets the reader a thousand times, and that is a visible part of how a mailing looks. How to connect one and what it changes is in the article on custom domains;
- tag before uploading, not after. Changing UTM parameters on a thousand links that already exist costs more than assembling a tagged column in a spreadsheet beforehand. The broader logic of tagging campaigns is covered in the piece on short links in marketing.
In short
Build a file of one or two columns, addresses carrying the https:// scheme, values containing commas in quotes. Set shared parameters on the batch; put differing ones into the addresses themselves or spread them across several uploads. Test on ten rows, then upload the rest and read the per-row report.
The section itself and the step-by-step order of actions are on the bulk URL shortener page; bulk upload is available on the paid plans, so a first batch needs an account on Pro or above.
