Usage & limits

Learn how to monitor your API usage, understand plan limits, and optimize your ButterCMS consumption.

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

To check your current usage:

1. Log in to your ButterCMS dashboard
2. Navigate to Settings > Billing
3. View your usage summary showing:
   • Current API calls used this billing period
   • Bandwidth consumed
   • Content counts (pages, posts, collection items)
   • Days remaining in billing cycle

Usage indicators

ButterCMS provides visual indicators for your usage:

Indicator	Meaning
Green	Well within limits
Yellow	Approaching limits (70-90%)
Red	At or exceeding limits

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

Use the fields parameter to reduce response sizes and processing:

// Only request the fields you need
const response = await butter.page.list('landing-page', {
  fields: 'slug,fields.headline,fields.hero_image'
});

Batch related requests

Combine related content fetches when possible:

// Instead of multiple calls
// const pages = await butter.page.list('landing-page');
// const posts = await butter.post.list();

// Use parallel requests if you need both
const [pages, posts] = await Promise.all([
  butter.page.list('landing-page'),
  butter.post.list()
]);

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: You’ll see a warning when you’re at 90% of your limit
• 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

While some plans have unlimited locales, others have a fixed limit:

• Each locale version of content counts toward your content limits
• Example: 1 page in 3 locales = 3 pages toward your limit

Overage charges

Simple, predictable overage pricing:

• API Calls: $10 per million additional API calls
• Bandwidth: $0.20 per GB of additional bandwidth

How overages work

1. Threshold reached: You exceed your plan’s included usage
2. Overage counted: Additional usage is tracked
3. Billed at end of cycle: Overages appear on your next invoice

Preventing unexpected overages

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

Prevention strategies:

1. Monitor usage weekly - Check your billing dashboard regularly
2. Implement caching - Reduce redundant API calls
3. Optimize images - Use the Image API for efficient delivery
4. Plan for traffic spikes - Upgrade before big launches or campaigns
5. 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 billing month resets.

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 in your billing dashboard
• 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 sends notifications when you approach plan limits:

Notification thresholds

Threshold	Notification
70%	Warning email
90%	Urgent warning
100%	Limit reached notification

Managing notifications

Ensure you receive usage alerts:

1. Verify your account email is correct
2. Check that ButterCMS emails aren’t marked as spam
3. Add your finance team to receive billing notifications

Frequently asked questions

Do unused API calls roll over to the next month?

No, API call allocations reset at the start of each billing cycle. 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 are charged overage fees on the next invoice. 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?

Navigate to Settings > Billing in your ButterCMS dashboard to see your current usage for the billing period.

Can I get a usage report for my team?

Your billing 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.