---
title: "Shorten up to 100 URLs"
method: POST
path: "/shorten/batch"
tags: ["URLs"]
---

# Shorten up to 100 URLs

`POST /shorten/batch`

## Request

- Base URL: `https://gajo.io/api/v1`
- URL: `https://gajo.io/api/v1/shorten/batch`
- Auth: API key in header `x-api-key`

**Requires a Pro plan.** Creates up to 100 short links in one request. Each item takes the same fields as `POST /shorten` and is processed independently: the response lists a success or an error for every item, in request order, and the request itself still returns `200` when some items fail. Each created link counts against your monthly URL allowance; items beyond the allowance fail individually.

## Request body

- BatchShortenRequest
  - `urls` ShortenRequest[], required: Up to 100 links, each with the same fields as `POST /shorten`.
    - `url` string, required: Destination URL. Supported schemes: `http`, `https`, `mailto`, `tel`, `ftp`, `sftp`. Pro plans may also shorten app deep links with a custom scheme (e.g. `myapp://product/42`). URLs pointing at gajo.io are rejected.
    - `customCode` string, nullable: Pro only. A custom code for the link (3-50 letters, digits, or hyphens; stored lowercase). The link redirects at `https://gajo.io/c/{code}` and the response has `isCustomCode: true`. An unclaimed code is claimed for you; one of your own codes is reused if it isn't linked to a URL. Can't be combined with `lifetimeDays`.
    - `lifetimeDays` integer, nullable: Days until the link expires. Omit for your plan maximum. Values above the plan maximum are clamped to it (60 on Free, 120 on Basic); Pro has no maximum, and omitting it on Pro creates a link that never expires.
    - `fallbackUrl` string, nullable: Only valid when `url` is an app deep link (custom scheme, which requires Pro). A web URL that visitors are sent to when the app is not installed, such as the App Store or Google Play listing. Sending it with an ordinary web `url` is rejected with `400`.

## Response `200`

Per-item results.

- BatchShortenResult: Envelope shared by every response.
  - `success` true, required: `true` when the request succeeded.
  - `message` string, nullable: Human-readable status or error message. Often `null` on reads.
  - `data` BatchShortenItem[], required: Operation-specific payload; `null` or absent when there is nothing to return.
    - union: Per-item outcome, in request order.
      - BatchShortenItemSuccess
        - `success` unknown, required
        - `url` ShortUrl, required: A short link. Generated codes redirect at `https://gajo.io/{shortCode}`; custom codes (`isCustomCode: true`, created in the Pro dashboard) redirect at `https://gajo.io/c/{shortCode}`. All redirects are HTTP 302.
          - `shortCode` string, required: The short code. Generated codes are never reassigned.
          - `originalUrl` string, required: Destination URL (may be an app deep link on Pro).
          - `fallbackUrl` string, nullable, required: Web fallback used when `originalUrl` is an app deep link and the app is not installed (e.g. the App Store listing). `null` otherwise.
          - `active` boolean, required: `false` once the link has been deactivated.
          - `clickCount` integer, required: Human clicks (bot and link-preview traffic excluded).
          - `isCustomCode` boolean, required: `true` for Pro custom codes (served under `/c/`).
          - `createdDate` string, date-time, required
          - `expiresDate` string, date-time, nullable, required: When the link stops redirecting; `null` = never expires.
      - BatchShortenItemFailure
        - `success` unknown, required
        - `error` string, required: Why this item was not shortened (validation error or monthly limit).
        - `originalUrl` string, required: The `url` from the request item.

## Other responses

- `400`: Invalid request. `message` explains what to fix.
- `401`: The `x-api-key` header is missing, or the key is unknown or revoked.
- `403`: Your plan is not Pro (the message names the Pro feature).
- `429`: Per-minute rate limit exceeded. Wait `Retry-After` seconds.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/gajo/apis/gajo-api.md) · [All operations](https://skmtc.dev/gajo/apis/gajo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gajo/apis/gajo-api/revisions/de6fe920cc26?raw)