# Limits

Every limit on the Clikso API by plan, from requests per minute and API keys to monthly links and the analytics quota, and what you get back when you reach one.

> **In short:**
>
> Each API key can send a set number of requests a minute, based on your plan. On top of that, some allowances count per workspace: links a month, analytics calls, and AI slugs. When you reach a limit, you get a `429` or a `402` that says which one.

## Limits by plan

| Limit                                                                | Free    | Starter | Pro      | Business  |
| -------------------------------------------------------------------- | ------- | ------- | -------- | --------- |
| API requests per minute (Per key)                                    | 30      | 100     | 300      | 500       |
| API keys (Per workspace, revoked keys excluded)                      | 3       | 10      | 20       | 30        |
| New links per month (Per workspace, per billing month)               | 50      | 500     | 5,000    | 10,000    |
| Analytics requests per minute (Per workspace, shared by all keys)    | 5       | 10      | 30       | 60        |
| Analytics requests per day (Per workspace, resets at 00:00 UTC)      | 100     | 1,000   | 5,000    | 20,000    |
| Click history you can read (Older clicks are left out, not an error) | 30 days | 90 days | 180 days | 365 days  |
| AI slug suggestions per day (Per workspace, resets at 00:00 UTC)     | 10      | 30      | 200      | Unlimited |
| Folders                                                              | 3       | 6       | 15       | 40        |
| Tags                                                                 | 5       | 10      | 20       | 50        |
| Custom domains (Plus the free Clikso domains)                        | 1       | 2       | 5        | 12        |

Prices for each plan are on the [pricing page](https://clik.so/pricing).

## Requests per minute

Each key has its own limit, counted in one-minute windows. Two keys in one workspace each get the full amount.

Go over it and you get `429 RATE_LIMITED`. The `Retry-After` header says how many seconds to wait. The next minute starts clean, and nothing is blocked for longer.

There is also a limit on failed key checks. One IP address can fail 30 checks a minute. Past that, its failed checks get `429 RATE_LIMITED` until the minute ends. Requests with a valid key are not affected.

## Analytics quota

Click analytics calls cost more to answer, so they have their own quota. It counts per workspace, and every key in the workspace shares it.

* **Per minute.** Over it, you get `429 RATE_LIMITED` with a `Retry-After` header.
* **Per day.** The day runs from midnight to midnight UTC. Over it, you get `429 USAGE_LIMIT_REACHED`, and `error.details.resets_at` says when it starts again.

If you send the same request twice within 60 seconds, the second answer comes from a cache. It still counts toward the quota.

Every analytics response has these headers, so you can slow down before you hit a limit:

* `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` — for the current minute.
* `X-Analytics-Quota-Limit` and `X-Analytics-Quota-Remaining` — for the current UTC day.

Analytics calls also count toward the key's own requests per minute. See [Click analytics](https://clik.so/docs/guides/analytics) for the calls themselves.

### Click history

Each plan can read clicks from a set number of days back. That is the "Click history you can read" row above. If you ask for an older start date, Clikso moves it forward to the oldest day your plan can read. This is not an error. The response tells you it happened, with `retention_clamped` and `effective_from`.

## Per-route limits

Two endpoints have their own limits, per workspace:

* **AI slug suggestions** (`POST /links/ai-slug`): up to 15 calls a minute, and the daily number in the table above. The day resets at midnight UTC. See [AI slugs](https://clik.so/docs/guides/ai-slugs).
* **Link previews** (`POST /links/og-preview`): up to 30 calls a minute.

## Monthly links

Each plan can create a set number of new links in a monthly period. The period starts on your billing day, not on the 1st. Read your count, and when it resets, with [Get usage](https://clik.so/docs/api/workspace/get-usage).

When you reach the limit, `POST /links` returns `429 USAGE_LIMIT_REACHED` until the next period. Changing, archiving and reading links still work.

Clicks are never blocked. Your short links keep redirecting, however many clicks they get.

## API keys

The number of keys only matters when you create one. Revoked keys do not count, so you can always swap an old key for a new one. Each browser connected to the Clikso extension holds a key too, and those count. If you move to a smaller plan, the keys you already have keep working.

## Folders and tags

Each plan can hold a set number of folders and tags. An API key that tries to create one more gets `402 UPGRADE_REQUIRED`. Renaming, deleting and using the ones you have always work.

## Size limits

These limits apply on every plan:

* **Bulk changes:** up to 100 link ids per call.
* **Lists:** up to 200 links per page. `meta.total` stops counting at 10,000, so page with `has_more`.
* **Analytics filters:** up to 100 values in each filter list.
* **Analytics by domain:** a domain filter covers up to 250 links. When it is cut short, `link_filter_truncated` is `true`.
* **Analytics breakdowns:** the top 250 values in each list, such as countries or referrers.
* **Raw clicks:** the newest 1,000 clicks per call.

## What you get back

When you reach a limit, the status and code tell you which kind:

* `429 RATE_LIMITED` — too fast. Wait for `Retry-After`, then try again.
* `429 USAGE_LIMIT_REACHED` — an allowance is used up for now. Wait for the reset, or upgrade.
* `402 UPGRADE_REQUIRED` — your plan does not include this, or you have all the folders or tags it allows.

## Common errors

| Status | Code                  | What it means                                                                             | What to do                                                              |
| ------ | --------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| 402    | `UPGRADE_REQUIRED`    | A field needs a higher plan, or a new folder or tag is past your plan’s count.            | Leave the field out, or upgrade the workspace.                          |
| 429    | `RATE_LIMITED`        | Too many requests this minute, for this key or for the workspace’s analytics or AI slugs. | Wait the number of seconds in the `Retry-After` header, then try again. |
| 429    | `USAGE_LIMIT_REACHED` | Links this month, AI slugs today or analytics calls today are used up.                    | Wait for the reset (analytics sends `details.resets_at`) or upgrade.    |

## Good to know

* Spread big jobs out. A short pause between calls keeps you well under the limit.
* When you get a `429 RATE_LIMITED`, always honour `Retry-After` before you try again.
* A higher plan raises these limits once the plan change goes through.

---

Source: https://clik.so/docs/limits