Image Caching & Performance

How Caching Works with the GET Render Endpoint#

The GET render endpoint (/api/v1/render) automatically caches every rendered image. When a request comes in:

1. RenderStack generates a unique cache key based on the template, layer overrides, output format, quality, and dimensions
2. If a cached image exists for that key, it is served directly from cloud storage (S3/CloudFront)
3. If no cache entry exists, the image is rendered, stored in cloud storage, and the result is returned

Cached renders are significantly faster (typically under 50ms vs several hundred milliseconds for a fresh render) and do not count against your render quota.

Understanding Cache Response Headers#

Every response from the GET render endpoint includes headers that indicate the cache status:

Header	Value	Meaning
X-Cache	HIT	The image was served from cache
X-Cache	MISS	The image was freshly rendered and has now been cached
X-Cache-Source	cloudfront	Served via CloudFront CDN (fastest)
X-Cache-Source	s3-proxy	Streamed from S3 storage
Cache-Control	e.g. public, max-age=86400, s-maxage=604800	Browser and CDN cache durations
ETag	Cache key hash	Used for conditional requests

Cache TTL and Plan Limits#

Cache duration and capacity vary by subscription plan:

Plan	Max Cache Entries	Cache TTL	Browser Cache	CDN Cache
Starter	50	1 day	1 hour	1 day
Pro	500	7 days	1 day	7 days
Business	2,000	14 days	1 day	14 days
Enterprise	10,000	30 days	1 day	30 days

When the cache is full, the oldest entries are automatically evicted to make room for new ones.

Viewing Cache Usage#

You can view your current cache usage on the Billing page in your organization settings. The Cache Usage section shows:

• Current cache entries vs your plan limit (with a progress bar)
• Cache hit rate over the last 30 days
• Estimated renders saved by caching
• Cache storage size

Purging Cached Images#

You can purge cached images via the API using your API key:

Purge a single cache entry#

DELETE /api/v1/cache/:cacheKey
Authorization: Bearer YOUR_API_KEY

Purge all cache for a template#

DELETE /api/v1/cache/template/:templateId
Authorization: Bearer YOUR_API_KEY

Purge all cache for your organization#

DELETE /api/v1/cache
Authorization: Bearer YOUR_API_KEY

You can also purge all cache from the Settings page if you are on an Enterprise plan with self-service cache management enabled.

Automatic Cache Invalidation#

Cached images are automatically invalidated when:

• The underlying template is edited (any change to layers, canvas size, or settings)
• A cache entry reaches its TTL expiration
• Cache entries are evicted due to capacity limits

This ensures you never serve stale content after making template changes.

CDN Considerations#

RenderStack uses optimized HTTP cache headers that work with CDNs like Cloudflare and CloudFront:

• Cache-Control — Includes public, max-age (browser cache), s-maxage (CDN cache), and stale-while-revalidate directives
• ETag — Enables conditional requests for cache validation
• Vary: Accept — Ensures correct content negotiation

Configuring Cloudflare Cache Rules#

If your API requests pass through Cloudflare, configure a Cache Rule for the /api/v1/render path:

1. In Cloudflare Dashboard, go to Caching > Cache Rules
2. Create a rule matching the URI path /api/v1/render*
3. Set Cache eligibility to "Eligible for cache"
4. Set Edge TTL to respect origin headers
5. Enable Browser TTL to respect origin headers

This ensures Cloudflare caches rendered images at the edge, reducing latency for geographically distributed users.

Enterprise Self-Service Cache Settings#

Enterprise customers with the self-service cache management feature enabled can customize their cache configuration directly from the Settings page:

• Cache TTL — How long cached images are stored
• Browser Cache TTL — How long browsers cache images locally
• CDN Cache TTL — How long CDN edge nodes cache images
• Stale-While-Revalidate — Grace period for serving stale content while refreshing
• Max Cache Entries — Maximum number of cached images

Non-Enterprise plans use plan-level defaults that cannot be changed. Contact support or upgrade to Enterprise for custom cache configuration.

Best Practices#

• Use consistent parameters — The cache key is based on exact parameter values, so use consistent formatting for best hit rates
• Monitor your hit rate — A high cache hit rate (above 70%) indicates efficient caching; a low rate suggests highly dynamic content
• Purge strategically — Only purge when content has actually changed; unnecessary purges reduce cache effectiveness
• Leverage CDN caching — If using Cloudflare or another CDN, configure it to respect RenderStack cache headers for maximum performance

Important: Configuration vs Feature Availability#

Cache configuration changes made through the admin panel or your organization settings (such as changing cache TTL values, adjusting max entries, or purging cache) are stored in the database and take effect immediately on all subsequent requests.

However, the cache management features themselves (the UI pages, API endpoints, and response headers described in this article) are part of the application codebase. These features are only available publicly after the application has been republished (deployed to production) by the developer. If you do not see a feature described in this article, it may not yet be deployed to the live environment. Contact your platform administrator for deployment status.