Caching and performance

How SpreadAPI keeps answers fast: which answers are stored and for how long, why the first call can take longer, and how a caller gets a fresh result when it matters.

How answers are kept fast

Repeated calls are fast because results are stored by the service itself, and nowhere else:

• Stored results. When a call has exactly the same inputs as an earlier call, the stored answer is returned instead of calculating again. A stored result is used for up to 15 minutes.
• No copies outside the service. Answers are not stored by browsers or networks. Every call reaches the service, so a republish, a new token or unpublishing applies to the next call.

Stored results are safe for a normal model: the same inputs give the same outputs. They matter when your workbook depends on something else than the inputs, such as the current time, random numbers or connected data.

The first call

The first call after publishing, or after the service was not used for a while, takes longer because the workbook has to be loaded. The calls after it are much faster. Opening API → Test prepares the service, so a test call there is usually quick already.

Large workbooks take longer to load than small ones. Tips for lean models are in Workbook tips.

See what happened

Every answer says how it was made, in metadata:

• executionTime: the calculation time in milliseconds.
• totalTime: the total time on the server in milliseconds.
• cached: true: the answer came from a stored result.

The Usage tab shows the average response time of the service over time; see Usage overview.

Get a fresh result

Add one of these to a call:

On GET they are part of the address:

https://spreadapi.io/api/v1/services/{serviceId}/execute?amount=20000&rate=0.05&nocache=true

On POST they are fields of the body, next to inputs:

{ "inputs": { "amount": 20000, "rate": 0.05 }, "nocache": true }

Use nocache=true only where it is needed. A recalculation is slower than a stored answer.

After you republish

When you republish, results stored for the previous version are no longer used. The next call with any inputs is calculated with the new version.

Answers are not stored by browsers or networks, so no older copy of an answer is left anywhere. The app confirms with "Service republished. New calls use the new version.".

If results still look old after that, see Wrong or old results.

Workbooks that change by themselves

Some workbooks give different results for the same inputs:

• Functions such as NOW, TODAY, RAND and RANDBETWEEN.
• Data loaded through a data connection.

A stored result repeats the earlier answer for these. Choose what fits:

• Let callers send nocache=true when they need the current value.
• Pass the changing value as an input, for example the date, so each value has its own result.
• For workbooks with a data source, shorten Cache duration: (Cache-Dauer) under Settings, or switch off Cache data from data sources (Daten aus Datenquellen cachen) so that every calculation reads the data source. See Service settings.

Connected data

For workbooks with a data source, the records are reused for the Cache duration: set under Settings: 1, 5, 15, 30 minutes or 1 hour, 5 minutes by default. During that time calculations use those records instead of reading the data source again.

A stored result of such a service is used only while the records it was calculated with are unchanged, and for the cache duration at most instead of 15 minutes. nocache=true reads the data source for that call. With Cache data from data sources off, every calculation reads the data source and no results are stored. See Live data from a data source.

Limits that affect speed

• At most 1,000 calls per minute per service, all callers together. Over that, calls answer HTTP 429 with RATE_LIMIT_EXCEEDED and a Retry-After header.
• A call has up to 30 seconds to answer.
• The calls per month of the plan; see Call limits.

A stored result that SpreadAPI returns still counts as a call.

Tips for fast clients

• Reuse results on your side when the same inputs are asked again within a short time.
• Use Batch calls for many input sets instead of many single calls in a loop.
• Keep the outputs to what the client needs. A large cell range as output means a larger answer.
• When you get 429, wait the seconds given in Retry-After before trying again.

Related

• The API response
• Limit errors
• Publish, republish and unpublish

For developers and agents

Input names are compared without regard to upper and lower case, and the order of the inputs does not matter for a stored result. Token checks happen on every call, also when the answer comes from a stored result.

A 429 for the per-minute limit has the body {"error": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Maximum 1000 requests per minute.", "timestamp": "...", "details": {"limit": 1000, "reset": 1698765432}}, where reset is a Unix time in seconds.

FAQ

Why does my API return the same result although I changed the workbook?

Callers get the published version, and identical calls may be answered from a stored result. Save and republish; the next call is answered by the new version.

How do I force a fresh calculation?

Add nocache=true to the address on GET, or "nocache": true to the POST body. The call then skips the stored result and calculates again.

How long are results cached?

A stored result for identical inputs is used for up to 15 minutes. Browsers and networks do not store answers. Republishing drops the stored results of the old version.

What is the difference between nocdn and nocache?

nocache=true skips the stored result and recalculates. nocdn=true is still accepted but no longer needed, because answers are not stored by browsers or networks.

Why is the first call slow?

The workbook has to be loaded for the first call after publishing or after a quiet period. Later calls reuse it and are much faster.

My workbook uses TODAY or RAND. Will callers get old values?

For identical inputs a stored result repeats the earlier value for up to 15 minutes. Have callers send nocache=true, or pass the changing value as an input.

Can I switch caching off for my service?

For workbooks with a data source, yes: switch off Enable response caching under Settings, save and republish. For other workbooks caching is always on, and a caller uses nocache=true for a fresh result.

Do cached answers count toward my calls?

A stored result returned by SpreadAPI counts as a call like any other. The limits are described in Call limits.

How do I see whether an answer was cached?

Look at metadata.cached in the answer. It is true when the answer came from a stored result.

How many calls per minute can my service take?

At most 1,000 calls per minute per service, all callers together. Beyond that, calls answer HTTP 429 until the minute has passed.

As an agent, should I always send nocache=true?

No. Use the default for normal questions, because identical inputs give identical results and stored answers are faster. Send nocache=true only when the user just republished or the model depends on time, random numbers or live data.