For how long is it safe to cache a Prismic API ref

For our server-side rendered app, we want to avoid the overhead of fetching the Prismic API ref for every single requests. The ~200-300ms it takes to load the master ref are critical.

For this, we use a stale-while-revalidate mechanism to ensure most users never have to pay the cost of loading the API ref:

  • The API ref is cached and considered fresh for 30 seconds. After this period of time, it becomes stale but can be used while we refresh it in background.
  • A stale API ref can be used for maximum 5 minutes. After this period of time, we must refresh the ref before requesting any Prismic document.

This logic is based on the assumption that if a document is published, the master ref will change but the previous ref will eventually stay valid for a short period of time (5 minutes based on our tests).

However, in some rare cases, we saw that a ref could expire almost immediately after a document is published, causing some errors because we are using a cached ref which has expired.

Could you share some more info regarding this?

  • For how long is it safe to cache an API ref after a document is published?
  • Does publishing many documents in row or a big release impacts the duration of a ref?

Hi Paul,

Welcome to the community!

We don't recommend caching at all:


Thanks for you answer. @Phil. I do understand that not caching at all is the simplest solution.

We just realised that in many cases, fetching the Prismic ref takes more time (up to 300ms) than requesting an entire Prismic document, which takes around 50ms when it is cached by your CDN :rocket:. That's why we tried to get around this problem.

Here is another solution we have in mind:
If the Prismic ref changes only when a document is published, we could cache the ref and listen to Prismic webhook to know when to refresh it.

Do you see any potential issues with this solution?

Hi again Paul,

So I think the team might be working on providing a faster Prismic Ref response this would hopefully be the solution you're looking for. I'm not 100% what the status of this is, but if you provide me with your repo URL I can try and get the BETA activated on your repo.


1 Like

Why can't you answer his question? It sounds reasonable to do that paul2 is saying, and cache the ref - whats the issue with that?

I feel I did answer his question in the post I linked:

So it's never really safe to cache the endpoint as it changes with every document update.

Also as we talked about we recently replicated the API ref endpoint in London for our European customers to have a faster response time on that endpoint, we will do the same for our Asian customers soon, so hopefully, there shouldn't be much need to cache the endpoint soon if everyone is already satisfied with the response time.

This topic was automatically closed 24 hours after the last reply. New replies are no longer allowed.