Usage & limits - ButterCMS Docs

ButterCMS plans scale based on API calls, bandwidth, and asset storage, so you pay for what you actually use, not for access to features. Understanding your usage helps you choose the right plan and avoid unexpected overages.

Understanding usage metrics

ButterCMS tracks three primary usage metrics that determine your plan limits and potential overages:

API calls

An API call is any request made to the ButterCMS API. This includes:

Request Type	Counts as API Call
Fetch a single page	✅
List pages	✅
Retrieve a blog post	✅
List blog posts	✅
Fetch collection items	✅
Image transformations	❌*
Webhook deliveries	❌

*Image API requests through the CDN don’t count toward your API call limit.

Each API request to endpoints like /v2/pages/, /v2/posts/, or /v2/content/ counts as one API call, regardless of how many items are returned.

Bandwidth

Bandwidth measures the total data transferred when serving your content and media assets through the ButterCMS CDN. What counts toward bandwidth:

Media file downloads (images, videos, documents)
API response payloads
CDN-served content

Factors affecting bandwidth:

Number of visitors to your site
Size of media files
API response sizes (controlled by field selection)

Asset storage

Asset storage is the total disk space used by files uploaded to your Media Library:

Images (JPG, PNG, WebP, GIF, SVG)
Videos (MP4, WebM)
Documents (PDF, DOC, etc.)
Audio files

Plan limits by tier

Metric	Free	Basic	Advanced	Professional	Enterprise
API Calls/month	50,000	100,000	500,000	1,000,000	Custom
Bandwidth/month	100 GB	250 GB	500 GB	1 TB	Custom
Pages	5	20	50	100	Custom
Blog Posts	50	100	500	Unlimited	Custom
Collection Items	50	100	500	1,000	Custom
Locales	❌	❌	❌	3	Custom
Roles	2	2	3	3	Unlimited
Users	Unlimited	Unlimited	Unlimited	Unlimited	Unlimited

Monitoring your usage

Viewing current usage

Usage figures live in two places in the ButterCMS dashboard (the Billing page doesn’t show them):

Home dashboard: the Usage card shows current/limit pairs, for example “42,500 / 100,000” Total API Requests for the current month, plus Pages, Blog posts, Collections, Locales, Assets and Total users. Metrics without a plan cap show “Unlimited”.
Analytics: select Analytics in the navigation menu for charts over time. Once a metric reaches 80% of its plan quota, a dashed Plan Limit line appears on that chart. See Monitoring API Usage.

Bandwidth usage isn’t shown in the dashboard. If you need your current bandwidth figure, contact support.

API and bandwidth usage resets at the start of each UTC calendar month, which may not line up with your subscription’s billing/renewal date.

Check your usage regularly, especially during high-traffic periods or after launching new features that may increase API calls.

Optimizing API usage

Reduce your API call consumption with these strategies:

Implement caching

Cache API responses to avoid repeated calls for the same content:

// Example: Simple in-memory cache
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getPageWithCache(slug) {
  const cacheKey = `page:${slug}`;
  const cached = cache.get(cacheKey);

  if (cached && Date.now() < cached.expiry) {
    return cached.data;
  }

  const response = await butter.page.retrieve('*', slug);
  cache.set(cacheKey, {
    data: response,
    expiry: Date.now() + CACHE_TTL
  });

  return response;
}

Use static site generation (SSG)

For static sites, fetch content at build time instead of on every request:

Next.js: Use getStaticProps with revalidate
Nuxt: Use generate or asyncData in static mode
Astro: Content is fetched at build time by default

Leverage webhooks for cache invalidation

Instead of polling for updates, use webhooks to invalidate caches only when content changes:

// Webhook handler to invalidate cache
app.post('/webhook/butter', (req, res) => {
  const { type, data } = req.body;

  if (type === 'page.published' || type === 'page.updated') {
    cache.delete(`page:${data.slug}`);
  }

  res.status(200).send('OK');
});

Request only needed fields

Reduce response size by passing exclude_body: true to blog post calls, or limiting reference depth with levels:

// Drop the body field from a blog post listing
const response = await butter.post.list({ exclude_body: true });

Running independent requests in parallel with Promise.all reduces latency, but each request is still a separate counted API call:

const [pages, posts] = await Promise.all([
  butter.page.list('landing-page'),
  butter.post.list()
]);

To actually reduce your call count, fetch multiple collections in a single request using the keys query parameter:

GET https://api.buttercms.com/v2/content/?keys=key_one,key_two&auth_token=YOUR_READ_API_TOKEN

This returns { "data": { "key_one": [...], "key_two": [...] } } as one counted API call instead of one call per collection.

Optimizing bandwidth

Optimize image sizes

Use the ButterCMS Image API to serve appropriately sized images:

<!-- Original large image -->
<img src="https://cdn.buttercms.com/abc123">

<!-- Optimized: resize and compress -->
<img src="https://cdn.buttercms.com/resize=width:800/compress/abc123">

<!-- Responsive images with srcset -->
<img
  src="https://cdn.buttercms.com/resize=width:800/abc123"
  srcset="
    https://cdn.buttercms.com/resize=width:400/abc123 400w,
    https://cdn.buttercms.com/resize=width:800/abc123 800w,
    https://cdn.buttercms.com/resize=width:1200/abc123 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
>

Use modern image formats

Convert images to WebP for smaller file sizes:

<!-- Automatic WebP conversion -->
<img src="https://cdn.buttercms.com/output=format:webp/abc123">

Enable compression

Ensure your frontend server has gzip/brotli compression enabled for API responses.

Lazy load media

Implement lazy loading for images and videos below the fold:

<img src="image.jpg" loading="lazy" alt="Description">

Content limits

Pages and Blog Posts

Each plan has limits on the number of pages and blog posts you can create:

Approaching limit: There is no advance warning. Watch the current/limit figures on the Home dashboard Usage card.
At limit: You won’t be able to create new content without upgrading or deleting existing content

Collection items

Collection items are limited per plan. Consider:

Consolidating similar collections
Archiving old items instead of keeping them
Upgrading if you consistently need more items

Locales

Locales are included on the Professional plan (3 locales) and Enterprise (custom). Translations don’t multiply your content counts: a page translated into 3 locales still counts as 1 page toward your page limit.

Overage charges

Paid plans are billed for API calls and bandwidth used above the plan’s included amounts. Overage rates depend on your plan and contract. Contact customer success for the rates that apply to your account.

How overages work

Threshold reached: You exceed your plan’s included usage
Overage counted: Additional usage is tracked
Billed: Overage charges are reflected on your invoice; contact support if you have questions about a charge

Preventing unexpected overages

Set up monitoring and alerts to catch usage spikes before they result in significant overages.

Prevention strategies:

Monitor usage weekly - Check the Usage card on your Home dashboard regularly
Implement caching - Reduce redundant API calls
Optimize images - Use the Image API for efficient delivery
Plan for traffic spikes - Upgrade before big launches or campaigns
Use webhooks - Avoid polling-based architectures

When to upgrade vs. pay overages

Consider upgrading your plan if you:

Consistently exceed limits by 20% or more
Have predictable, sustained growth
Need additional features from higher tiers

Overages may make sense if you:

Have occasional traffic spikes (product launches, viral content)
Are testing before committing to a higher tier
Have seasonal usage patterns

API blocking (429)

ButterCMS enforces monthly usage limits for API calls and bandwidth. If a Free or Trial account exceeds its monthly API call limit, API requests are blocked until the start of the next UTC calendar month.

Response when blocked

{
  "detail": "API Calls limit reached."
}

Responses may include a Retry-After header indicating the seconds remaining until the monthly reset.

What to do

Check usage on the Home dashboard Usage card or the Analytics page
Reduce calls (cache responses and avoid polling)
Wait for reset or upgrade if you consistently exceed limits

Paid plans use usage-based billing for API overages and are not blocked for exceeding monthly API call limits. If you see 429 on a paid plan, contact support.

Usage alerts

ButterCMS doesn’t send emails or show in-app warnings as you approach your API call or bandwidth limits. The first signal a Free or Trial account gets is the 429 response once it’s blocked. Check the Usage card and Analytics page yourself, or add alerting in your own application (see Setting up usage alerts).

Frequently asked questions

Do unused API calls roll over to the next month?

No, API call allocations reset at the start of each UTC calendar month (not your subscription’s renewal date). Unused calls don’t carry over.

What happens if I exceed my limits?

For content limits (pages, posts), you won’t be able to create new content until you upgrade or delete existing items. For API calls and bandwidth, paid plans may be billed for overage usage; Free/Trial accounts are blocked until the monthly reset.

Does caching reduce my API usage?

Yes, caching API responses in your application significantly reduces the number of calls to ButterCMS. This is one of the most effective ways to stay within limits.

Are image transformations counted as API calls?

No, image transformations via the CDN (resizing, format conversion) don’t count toward your API call limit.

How do I check my current usage?

Open the Home dashboard and look at the Usage card, or select Analytics in the navigation menu for charts over time. The Billing page doesn’t show usage.

Can I get a usage report for my team?

The Usage card on the Home dashboard shows overall account usage. For detailed analytics and breakdowns, see the Analytics dashboard (see Monitoring API Usage). For advanced reporting, contact support or consider the Enterprise plan.

​Understanding usage metrics

​API calls

​Bandwidth

​Asset storage

​Plan limits by tier

​Monitoring your usage

​Viewing current usage

​Optimizing API usage

​Implement caching

​Use static site generation (SSG)

​Leverage webhooks for cache invalidation

​Request only needed fields

​Batch related requests

​Optimizing bandwidth

​Optimize image sizes

​Use modern image formats

​Enable compression

​Lazy load media

​Content limits

​Pages and Blog Posts

​Collection items

​Locales

​Overage charges

​How overages work

​Preventing unexpected overages

​When to upgrade vs. pay overages

​API blocking (429)

​Response when blocked

​What to do

​Usage alerts

​Frequently asked questions

Understanding usage metrics

API calls

Bandwidth

Asset storage

Plan limits by tier

Monitoring your usage

Viewing current usage

Optimizing API usage

Implement caching

Use static site generation (SSG)

Leverage webhooks for cache invalidation

Request only needed fields

Batch related requests

Optimizing bandwidth

Optimize image sizes

Use modern image formats

Enable compression

Lazy load media

Content limits

Pages and Blog Posts

Collection items

Locales

Overage charges

How overages work

Preventing unexpected overages

When to upgrade vs. pay overages

API blocking (429)

Response when blocked

What to do

Usage alerts

Frequently asked questions