Limits

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

Prices for each plan are on the pricing page.

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 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.
• 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.

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

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.