Skip to main content
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 TypeCounts 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

MetricFreeBasicAdvancedProfessionalEnterprise
API Calls/month50,000100,000500,0001,000,000Custom
Bandwidth/month100 GB250 GB500 GB1 TBCustom
Pages52050100Custom
Blog Posts50100500UnlimitedCustom
Collection Items501005001,000Custom
Locales❌❌❌3Custom
Roles2233Unlimited
UsersUnlimitedUnlimitedUnlimitedUnlimitedUnlimited

​
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:
IndicatorMeaning
GreenWell within limits
YellowApproaching limits (70-90%)
RedAt 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'
});
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

ThresholdNotification
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

No, API call allocations reset at the start of each billing cycle. Unused calls don’t carry over.
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.
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.
No, image transformations via the CDN (resizing, format conversion) don’t count toward your API call limit.
Navigate to Settings > Billing in your ButterCMS dashboard to see your current usage for the billing period.
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.