# Understand Your Plan's Limits and Usage

> Source: https://agilitycms.com/docs/owners-admins/understand-your-plans-limits-and-usage

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.

> [!NOTE]
> This page doesn't restate plan contents or prices. For what each plan includes, see the [Agility pricing page](https://agilitycms.com/pricing). Your contract or order form takes precedence over anything on this page.

## Two kinds of limits

| Kind | Examples | Where it is defined |
| --- | --- | --- |
| **Plan limits** | Bandwidth per month, asset storage | Your plan, on the [pricing page](https://agilitycms.com/pricing), 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.

## What counts towards the rate limit

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](/docs/developers/content-fetch-api#api-rate-limits): "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](/docs/developers/content-delivery-and-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](/docs/developers/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".

## API requests on the pricing page

The [pricing page](https://agilitycms.com/pricing) 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](/docs/developers/content-fetch-api#api-rate-limits) 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.

## Technical limits

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](/docs/developers/content-fetch-api#api-rate-limits) |
| Content Fetch API request processing time | 30 seconds. Above that: `408` | Ask for less data per request | [Content Fetch API](/docs/developers/content-fetch-api#api-rate-limits) |
| Items per Content Fetch API list request (`take`) | Default 10, maximum 250 | Page with `skip` to get more | [Fetch API reference: get list](/docs/api-reference/fetch/get-list) |
| Linked content depth (`ContentLinkDepth`) | Default 1, maximum 5 | | [Content Fetch API](/docs/developers/content-fetch-api#content-link-depth) |
| 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](/docs/api-reference/management/post-instance-item-batch-workflow) |
| URL redirections per Management API save call | Up to 250 | Split larger sets into several calls | [Management API reference: URL redirections](/docs/api-reference/management/post-instance-url-redirections) |
| File upload size | Up to 1 GB | | [Introduction to Assets](/docs/editors/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](/docs/editors/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.

## How to see your usage

- **Your instance's usage.** [About Instances](/docs/owners-admins/about-instances#monitor-your-usage) describes how to monitor your usage and see when you are reaching your plan's limits.
- **Your organization's billing.** Organization Admins manage subscriptions and billing for each instance in the organization. Other users can see the organization but not its billing details. See [Organization FAQ's](/docs/owners-admins/organization-faqs) and [About Organizations](/docs/owners-admins/about-organizations).
- **Your own logs.** Log every `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](/docs/developers/handle-rate-limits-and-outages#monitoring).
- **The status page.** Platform incidents are posted at [status.agilitycms.com](https://status.agilitycms.com), where you can subscribe to notifications. See [SLA & Uptime](/docs/owners-admins/sla-and-uptime).

## How to reduce your usage

Each of these lowers the number of uncached requests, the bandwidth you use, or both.

### Cache on your side and clear it with webhooks

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](/docs/developers/webhooks) 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](/docs/nextjs/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](/docs/developers/handle-rate-limits-and-outages).

### Ask for the right amount per request

- **Ask for more per request.** Use `take` up to 250 on lists instead of many small pages, and `ContentLinkDepth` rather than one request per linked item.
- **Ask only for what you need.** A large `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](/docs/developers/fetch-api-status-codes-and-caching).

### Keep a local copy with Content Sync

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](/docs/developers/content-sync-explained) and the [Content Sync API](/docs/developers/content-sync-api).

### Control build bursts

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](/docs/developers/handle-rate-limits-and-outages)). Limit build concurrency. See [Troubleshooting "fetch failed" Errors in Next.js](/docs/nextjs/troubleshooting-fetch-failed-errors-in-next-js).

### Serve images in the right format

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](/docs/overview/image-best-practices) and [Image Transformation Reference](/docs/developers/image-transformation-reference).

## When you need more

You can upgrade your plan at any time. [About Instances](/docs/owners-admins/about-instances#upgrading-your-plan) 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.

## Related

- [Content Fetch API](/docs/developers/content-fetch-api)
- [Fetch API Status Codes and Caching](/docs/developers/fetch-api-status-codes-and-caching)
- [Handle Rate Limits and Outages Gracefully](/docs/developers/handle-rate-limits-and-outages)
- [Content Sync Explained](/docs/developers/content-sync-explained)
- [Content Delivery & CDN Architecture](/docs/developers/content-delivery-and-cdn-architecture)
- [About Instances](/docs/owners-admins/about-instances)
- [Agility pricing](https://agilitycms.com/pricing)

---

## Related pages

- [About Instances](https://agilitycms.com/docs/owners-admins/about-instances.md)
- [Starter Templates](https://agilitycms.com/docs/owners-admins/starter-templates.md)
- [Data Residency & Data Regions](https://agilitycms.com/docs/owners-admins/data-residency-and-data-regions.md)
- [Hosting, Security & Compliance](https://agilitycms.com/docs/owners-admins/hosting-security-and-compliance.md)
- [Disaster Recovery & Business Continuity](https://agilitycms.com/docs/owners-admins/disaster-recovery-and-business-continuity.md)
- [SLA & Uptime](https://agilitycms.com/docs/owners-admins/sla-and-uptime.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt