What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report
Instances
Plan limits versus API limits, what counts towards the rate limit (CDN-cached responses don't), how to see your usage, and how to reduce it.
Agility has two kinds of limits. Some come with your plan, such as bandwidth and asset storage. Others are technical limits in the APIs, such as how many uncached requests per second the Content Fetch API accepts and how many items one request can return. This page explains which is which, what counts towards the API rate limit, how to see your usage, and how to reduce it.
This page doesn't restate plan contents or prices. For what each plan includes, see the Agility pricing page. Your contract or order form takes precedence over anything on this page.
| Kind | Examples | Where it is defined |
|---|---|---|
| Plan limits | Bandwidth per month, asset storage | Your plan, on the pricing page, and your contract |
| Technical limits | Uncached requests per second, items per request, IDs per batch call | The API documentation |
You can reach a technical limit in seconds, for example with a burst of requests during a build. Plan limits such as bandwidth are measured per month. They need different fixes, so it helps to know which one you are looking at.
The Content Fetch API (REST) and the GraphQL API are served through a CDN. Each request is either served from the CDN cache or passed through to the API:
| Request | What happens | Counts towards the per-second rate limit? |
|---|---|---|
| Cached: the CDN already holds a response for that exact URL | The CDN answers it | No |
| Uncached: for example the first request for a URL | The request reaches the API | Yes |
From Content Fetch API: "If your response is cached on our CDN, it will not count towards your rate limit. Our API enforces a limit of 10 direct requests per 1 second." Content Delivery & CDN Architecture says the same: "a response served from the Agility CDN cache does not count against API rate limits."
When content is published, Agility invalidates the affected cached responses, so the next request for them goes through to the API (Fetch API Status Codes and Caching). Requests for many different uncached URLs at once, for example during a large static build, are what push you over the limit.
Bandwidth is a separate measure. The pricing page describes it as "The total bandwidth of assets and API calls available per month".
The pricing page lists API and asset requests as "Unlimited" on every plan it shows, described as "The total number of requests you can query on the API or assets."
The Content Fetch API documentation says "All requests have a per-second rate limit" and that the API enforces "a limit of 10 direct requests per 1 second", with a 429 response above it. Cached responses don't count.
For how these apply to your plan, contact your account team. Design your site for the documented per-second limit.
Every number in this table comes from a published Agility page, linked in the last column.
| Limit | Value | What to do | Source |
|---|---|---|---|
| Uncached (direct) Content Fetch API requests | 10 per second. Above that: 429 Too Many Requests | Cache, and retry with back-off | Content Fetch API |
| Content Fetch API request processing time | 30 seconds. Above that: 408 | Ask for less data per request | Content Fetch API |
Items per Content Fetch API list request (take) | Default 10, maximum 250 | Page with skip to get more | Fetch API reference: get list |
Linked content depth (ContentLinkDepth) | Default 1, maximum 5 | Content Fetch API | |
| Content IDs per Management API batch workflow call (publish, unpublish, approve, decline, request approval) | Maximum 250 | Split larger sets into several calls | Management API reference: item batch workflow |
| URL redirections per Management API save call | Up to 250 | Split larger sets into several calls | Management API reference: URL redirections |
| File upload size | Up to 1 GB | Introduction to Assets | |
| Files over 15 MB | Delivered with segmented caching over the CDN, and only for the listed file extensions | Use a listed extension. A file over 15 MB with another extension can't be downloaded through the CDN | Introduction to Assets |
For limits not listed here, such as request limits for the Management API, ask Agility support before you rely on a value.
429 and 408 from Agility with the URL that caused it, and count cache hits and misses on your side, so you can see which code path sends uncached requests. See Handle Rate Limits and Outages Gracefully.Each of these lowers the number of uncached requests, the bandwidth you use, or both.
Cache every published read in your framework's data cache with a long lifetime, and clear only what changed when content is published. An Agility webhook tells your app what was published. This turns most page renders into cache hits that don't call the API.
For the full pattern on Next.js, see Caching with Next.js and Agility. For the other layers (prerendering, retries with back-off, serving stale content on error), see Handle Rate Limits and Outages Gracefully.
take up to 250 on lists instead of many small pages, and ContentLinkDepth rather than one request per linked item.ContentLinkDepth, or ExpandAllContentLinks=true on a large list, makes a timeout more likely. Use fields to return only the fields you need. See Fetch API Status Codes and Caching.If you read the same content constantly, sync it into your own store and read from there. The pricing page describes Content Sync as "eliminating the need to make API calls to Agility unless content changes." See Content Sync Explained and the Content Sync API.
A static build of a large site is the most common source of 429 responses, because it renders many pages at once (Handle Rate Limits and Outages Gracefully). Limit build concurrency. See Troubleshooting "fetch failed" Errors in Next.js.
Add format=auto to Agility image URLs, so the CDN serves AVIF or WebP to browsers that support them. Don't add size parameters to SVGs. See Image Best Practices and Image Transformation Reference.
You can upgrade your plan at any time. About Instances suggests changing your plan if you need more users, dedicated support or more bandwidth, and contacting your Customer Success Manager to upgrade.
If you are close to a plan limit, or want to know what happens when an instance goes over one, contact your account team.