> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

### 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      |

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

## Optimizing API usage

Reduce your API call consumption with these strategies:

### Implement caching

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

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```html theme={null}
<!-- 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"
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
>
```

### Use modern image formats

Convert images to WebP for smaller file sizes:

```html theme={null}
<!-- 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:

```html theme={null}
<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

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

**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

```json theme={null}
{
  "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

<Info>
  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](../../support/contact-status/contact-support).
</Info>

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Are image transformations counted as API calls?">
    No, image transformations via the CDN (resizing, format conversion) don't count toward your API call limit.
  </Accordion>

  <Accordion title="How do I check my current usage?">
    Navigate to **Settings > Billing** in your ButterCMS dashboard to see your current usage for the billing period.
  </Accordion>

  <Accordion title="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](./monitoring-api-usage)). For advanced reporting, [contact support](../../support/contact-status/contact-support) or consider the Enterprise plan.
  </Accordion>
</AccordionGroup>