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

# API performance best practices

> ButterCMS API performance overview: query optimization, pagination, caching, CDN delivery, scaling, monitoring, and rate limits.

## Understanding the ButterCMS API architecture

ButterCMS provides a REST API that serves content through a globally distributed infrastructure. Content created through the dashboard or Write API is immediately available via read endpoints with automatic global distribution for optimized delivery.

{/* SOURCE: file_path="api-documentation/openapi/info/tags/system-info.yaml" section="Request Flow" */}

### Request flow

Read operations query cached content from edge locations, while write operations process through the primary API and trigger cache invalidation.

```mermaid theme={null}
flowchart TB
    A[Client Application]
    B[Edge Cache]
    C[API Server]
    D[Media Upload<br/>Validation<br/>Webhooks<br/>Cache Refresh]
    A -->|Request| B
    B -->|"Cache Hit (~50-100ms typical)"| A
    B -->|Cache Miss| C
    C -->|"Response (~200-500ms typical)"| B
    C --> D
```

## Performance topics

<CardGroup cols={2}>
  <Card title="Query Optimization" icon="magnifying-glass" href="./query-optimization">
    How to use `exclude_body`, `levels`, and ordering to minimize response size and serialization overhead
  </Card>

  <Card title="Pagination" icon="filter" href="./pagination">
    How to use page-based and offset-based pagination, infinite scroll, and archive page patterns
  </Card>

  <Card title="Filtering Requests" icon="sliders" href="./filtering-requests">
    How to filter by author, category, tag, and custom field values server-side
  </Card>

  <Card title="Caching Strategies" icon="database" href="./caching-strategies">
    Learn how to implement application-level caching for SSG, SSR, and SPA integrations
  </Card>

  <Card title="CDN & Global Delivery" icon="globe" href="./cdn-global-delivery">
    Learn how ButterCMS serves content from 150+ edge locations worldwide
  </Card>

  <Card title="Scaling for High Traffic" icon="chart-line" href="./scaling-high-traffic">
    Learn how to implement circuit breakers, graceful degradation, and traffic spike strategies
  </Card>

  <Card title="Monitoring API Usage" icon="chart-bar" href="./monitoring-api-usage">
    Learn how to track read/write API consumption and identify optimization opportunities
  </Card>

  <Card title="Rate Limits & Throttling" icon="gauge" href="./rate-limits-throttling">
    Learn how to handle rate-limited responses and avoid hitting API throttle limits
  </Card>
</CardGroup>

## Performance checklist

<AccordionGroup>
  <Accordion title="Before going to production">
    * [ ] Use `exclude_body=true` for all listing endpoints
    * [ ] Set appropriate `levels` parameter (default to 1-2)
    * [ ] Implement pagination with 10-25 items per page
    * [ ] Add application-level caching for frequently accessed content
    * [ ] Set up error handling with retry logic
    * [ ] Configure webhooks for cache invalidation
  </Accordion>

  <Accordion title="Monitoring & optimization">
    * [ ] Monitor API response times in your application
    * [ ] Track API usage in the ButterCMS Analytics dashboard (see [Monitoring API Usage](./monitoring-api-usage))
    * [ ] Review and optimize queries that exceed 500ms
    * [ ] Consider pre-fetching content for predictable navigation
  </Accordion>
</AccordionGroup>