Do this with AI
Install the cms-data-modeling-best-practices skill from Contentstack agent skills and connect the Content Modeler profile in MCP Profile Hub. Then ask your agent:
Go through every content type in my stack and report which ones are close to a limit: more than 300 fields in total, more than 20 Global fields, Modular Blocks nested 2 levels deep, or more than 80 block definitions in one Modular Blocks field. Suggest how to simplify the worst three, but don't change any schema.
New to this? Set up your AI workbench first.
Contentstack limits on one page
Contentstack limits are spread over dozens of documentation pages, and you usually find the right one after you hit the limit. This page collects the public limits in one place, grouped by area, so you can check a content model or a job before it fails.
Every value here comes from the public documentation and was checked in December 2026. Limits change, and many depend on your plan, so follow the docs link in each section for the current value.
What you'll learn
The API rate limits and why they are per organization
How deep you can include references in REST and GraphQL
The schema limits for content types, fields, Modular Blocks and Global fields
The limits for taxonomy, entry variants, assets, publishing, webhooks, Launch and the CLI
Which limits depend on your plan, and which guide helps when you hit one
How to read this page
Plan-dependent means the documentation says the value depends on your plan, or that Contentstack support can raise it. Default values apply when nothing else is set for your organization. Where two documentation pages disagree, the table gives the value from the most recently updated page and says so.
Two things to keep in mind before the tables:
Rate limits are per organization. Your builds, imports, scripts, Automate workflows and integrations all share them.
Cached Delivery API responses are not rate limited. Only requests that reach the origin count. They all still count toward your overall API usage.
API rate limits
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Content Delivery API, uncached requests | 100 per second per organization | Yes | HTTP 429 | |
Image Delivery API, uncached requests | Counts toward the CDA limit | Yes | HTTP 429 | |
GraphQL Content Delivery API, uncached requests | 80 per second per organization | Yes | HTTP 429 | |
Content Management API, reads | 10 per second per organization | Yes | HTTP 429 | |
Content Management API, writes | 10 per second per organization | Yes | HTTP 429 | |
CMA bulk actions | 1 request per second | Yes | HTTP 429 | |
Stack creation | 1 stack per minute per organization | No | Request rejected |
The X-RateLimit-Limit and X-RateLimit-Remaining response headers show your actual limit and what's left in the current second. When you hit a rate limit, read Fix 429 rate limit errors in builds, imports and bulk publish. For timeouts and 5xx errors, read ETIMEDOUT, 5xx and timeouts from the Delivery API.
Content Delivery API (REST)
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Request URL size on the CDN | 8 KB | No | HTTP 414 URI Too Long | |
Entries or assets per response | 100 by default; set more with limit and page with skip | No | You get the first page only | |
Content types per "get all content types" response | 100 | No | Page with skip | |
include_all_depth | 5 levels (include_all alone resolves 1) | No | Error | |
Reference paths per request (include[] or include_all) | 100 | No | Error; reduce depth or includes | |
Depth of a multiple content type Reference field | 3 levels | No | Not documented | |
Recursive embedded items (embedded_items_depth) | 5 levels | No | Values above 5 are clamped to 5 | |
Sync API page size | 100 items | No | You get a pagination_token for the next page |
Long $in lists and many includes push a URL past 8 KB. Nested references empty or error 141 covers both.
GraphQL Content Delivery API
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Nested reference depth | 3 levels | No | Query rejected | |
Reference depth in a where filter | 3 levels | No | Query rejected | |
Objects fetched in one query | 7,500 | No | Query rejected | |
Referenced items per Reference field | 100 | No | Page with skip and limit on the connection | |
Embedded items per JSON RTE field | 100 | No | Page the embedded items | |
Content types queried in one request | 3 | No | Query rejected | |
Response size | 7 MB | No | Query rejected | |
limit on a collection | 25 by default, 100 maximum | No | Page with skip | |
Content type schemas generated per request | 100 | No | Page the introspection schema |
GraphQL errors don't always come back as a non-200 status. GraphQL errors decoded lists the error codes and what each one means.
Content types, fields and Global fields
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Fields per content type, including nested fields | 400 | Default | Schema save rejected | |
Content type UID | 200 characters; letters, numbers and underscores | No | Schema save rejected | |
Content type description | 255 characters | No | Schema save rejected | |
Title field and Display Name | 200 characters | Default | Save rejected | |
Modular Blocks fields per content type | 5 | Default | Schema save rejected | |
Block definitions per Modular Blocks field | 100 | Default | Schema save rejected | |
Block instances per Modular Blocks field in an entry | 100 | Default | Entry save rejected | |
Nested block levels | 2 | Default | Schema save rejected | |
Group nesting | 5 levels | Default | Schema save rejected | |
Fields in a Group, including nested fields | 100 | Default | Schema save rejected | |
Global fields per content type | 25 | Default | Schema save rejected | |
Global fields per organization | 1,000 | Default | Creation rejected | |
Fields within a Global field | 100 | Default | Schema save rejected | |
Global field nesting | 5 levels, including the parent | Default | Schema save rejected | |
Instances of a Global field marked Multiple | 100 | No | Entry save rejected | |
Custom fields per content type | 10 | Default | Schema save rejected | |
Select field options | 100, each up to 100 characters | Default | Schema save rejected | |
Field visibility rules per content type | 10 rules, 5 conditions and 5 target fields each | Default | Schema save rejected | |
Reference field query limit | 100 | No | Not documented | |
Tags per entry | 50, each up to 50 characters | No | Entry save rejected |
Watch for: The Field Limitations page (updated November 2026) gives 400 fields per content type and 100 fields within a Global field. The older content type and Global field pages say 500 for both. Plan against the lower number.
Fields inside Modular Blocks, Groups and Global fields all count toward the content type total. Modular Blocks, references or Global fields helps you pick the structure that keeps the count down.
Taxonomy
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Taxonomies per stack | Depends on your plan | Yes | Creation rejected | |
Terms per taxonomy | 10,000 | No | Term creation rejected | |
Terms per entry | 25 | No | Entry save rejected | |
Term depth | 10 levels | No | Term creation rejected | |
Taxonomy and term name or UID | 50 characters | No | Save rejected | |
Taxonomy fields per content type | 1, which can hold several taxonomies | No | Not possible to add a second |
The Taxonomy field can't go inside Modular Blocks or Groups, and only published taxonomies are available through the Delivery API. Querying content by taxonomy shows how the limits shape queries.
Entry variants
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Variants merged with the base entry per CDN request | 3 | No | Only 3 variants are merged | |
Timeout for entry variant requests | 10 seconds | No | Request fails | |
Response size, all variants of an entry | 10 MB | No | Request fails | |
Response size, a single entry variant | 3 MB | No | Request fails |
Entry variants need to be enabled for your organization, and custom queries only match base entry data. Personalize variant returns base entry or null covers the most common problems.
Stacks, branches, environments and locales
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Branches per stack | 5 | Yes | Creation rejected | |
Branch ID | 15 characters, lowercase, _ as separator | No | Creation rejected | |
Environments per stack | 5 | Default | Creation rejected | |
Fallback language levels | 1 | No | You can't chain fallbacks | |
Management tokens per stack | 10 valid at a time | No | Creation rejected | |
Authtokens per user | 20 valid at a time | No | Not documented |
The one-level fallback rule explains most "why am I getting en-us content" questions. Locale fallback explained walks through it.
Assets and images
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Asset file size | 700 MB in the UI, 100 MB through the API | Can be raised | Upload rejected | |
Assets per upload batch | 10 | Can be raised | Upload rejected | |
Assets per stack | 10,000 | Can be raised | Upload rejected | |
Image optimization input size | 50 MB | Can be raised | Not documented | |
Image optimization input dimensions | 12,000 × 12,000 pixels | Can be raised | Not documented | |
Image optimization output dimensions | 8,192 × 8,192 pixels | Can be raised | Not documented | |
Animated GIF frames | 1,000 | Can be raised | Not documented |
These apply to assets stored in a stack. The newer Assets product raises several of them. Image transforms that surprise you covers transform behavior.
Publishing, bulk operations and releases
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Bulk publish or unpublish in the UI | 100 entries, 10 languages, 10 environments at a time | Can be raised | Selection capped | |
Items per bulk publish API request | 10 | Plan feature | Split into more requests | |
Select all records | 10,000 entries | No | Only the first 10,000 are acted on | |
Bulk delete in the UI | 100 entries | Can be raised | Selection capped | |
Scheduled bulk action | Up to 12 months ahead | No | Date rejected | |
Nested reference publishing depth | 5 levels | Yes | Deeper references aren't published | |
Parent entries in a nested bulk publish | 100 | No | Selection capped | |
Active bulk publish jobs per organization | 2 | No | Extra jobs wait | |
Items in a release | 500 | No | Item not added | |
Items added to a release per API request | 25 | No | Split into more requests |
Nested reference publishing doesn't apply when you publish through a release. Releases, bulk publish and nested reference publishing explained compares the options, and Publishing stuck or references not published helps when a job doesn't finish.
Webhooks
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Webhooks per stack | 100 | Can be raised | Creation rejected | |
Conditions per webhook | 200 | No | Save rejected | |
Emails notified when the circuit breaker disables a webhook | 10 | No | Save rejected |
Webhooks: allowlisting, signatures and disabled endpoints covers the circuit breaker and how to get a disabled webhook running again.
Launch
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Request headers | About 10 KB | No | Request rejected | |
Request body | 128 KB on the platform limits page; the CF1001 error reference says 5 MB | No | Request rejected with 413 (CF1001) | |
Response headers | 32 KB | No | Response fails | |
Response body | 5 MB | No | Response fails | |
Cloud Function and SSR request timeout | 30 seconds by default, up to 780 seconds | Yes | Request times out | |
Time to first response byte | 98 seconds | No | Connection closes | |
Cache revalidations per day | 500 (Enterprise: 2,000) | Yes | Revalidation rejected until 00:00 UTC | |
Origin delivery rate | 200 requests per second (Enterprise: 1,200) | Yes | Origin requests throttled |
The origin delivery limit counts cache misses to your site's origin, separate from the API rate limits your code calls. Edge function limits, environment variable limits and log retention are in Logs, debugging and limits. The error codes you see when a Launch limit is hit are in Launch error codes decoded.
CLI
Limit | Value | Plan-dependent | When you hit it | Docs |
|---|---|---|---|---|
Request and response size (maxContentLength, maxBodyLength) | 100 MB by default | Configurable in the config file | Export or import fails | |
Share of the rate limit the CLI uses | 50% by default | Configurable with csdx config:set:rate-limit | Slower jobs, fewer 429s |
csdx import and export failures covers memory errors and other ways large CLI jobs fail.
Key takeaways
API rate limits are per organization: 100 uncached CDA requests per second, 80 for GraphQL, 10 reads and 10 writes for the CMA, 1 per second for bulk actions. Your plan can change all of them.
Cached Delivery API responses don't count against the rate limit, so caching is the cheapest way to stay under it.
REST includes go 5 levels deep with at most 100 reference paths. GraphQL goes 3 levels deep and returns at most 7 MB.
A content type holds 400 fields in total, counting everything inside Modular Blocks, Groups and Global fields.
Taxonomies allow 25 terms per entry and 10 levels of depth. Releases hold 500 items.
On Launch, server functions time out after 30 seconds by default, and responses are capped at 5 MB.
Values were checked in December 2026. Follow the docs link in each section for the current number.
Frequently asked questions
Are Contentstack rate limits per stack or per organization?
Per organization. Every stack, build, script and integration in the organization shares the same API rate limits.
Can Contentstack limits be raised?
Many can. Rate limits, nested reference publishing depth, the number of taxonomies and branches, and several asset and webhook limits depend on your plan or can be raised by Contentstack support.
How many fields can a content type have?
The Field Limitations page lists a maximum of 400 fields per content type, counting fields inside Modular Blocks, groups and Global fields.
How deep can I include references in one Delivery API request?
Up to 5 levels with include_all_depth on the REST Delivery API, and up to 100 reference paths per request. GraphQL fetches nested references up to 3 levels deep.
When were these values checked?
In December 2026, against the public Contentstack documentation. Each section links to the page it comes from, so check there for the current value.