Tools and cache management

Summary#

Tools & Cache lists all 65 tools in the catalog with their credit cost, the real cache lifetime each one uses, a control to override that lifetime and a button to purge their cached provider responses. It is the direct lever on the trade between the provider bill and data freshness. This page explains what each control writes, which tools it binds to, and where it silently does nothing.

Purpose#

Provider calls cost money. Caching a response and reusing it across customers is what keeps that bill sane, but the right lifetime is a judgement call that differs per tool: a backlink profile can be ten days old and still be useful, a rank check cannot. The screen exists so that judgement can be revised without a deploy, and so the current answer for every tool is visible in one table rather than scattered across the code.

Requirements#

• An active admin identity to read the screen. See Getting admin access.
• The owner role to change anything.
• MONITOR_DB bound, since both the settings and the cache live in D1.

Permissions#

Non-owners see the table with static text in place of the controls. The endpoints refuse them independently with 403 {"error":"Only an owner can change cache settings."} and 403 {"error":"Only an owner can clear the cache."}.

Navigation Path#

Admin console → Operations → Tools & Cache

How a lifetime is resolved#

For any provider call the worker picks the first of these that yields a positive number:

1. cache_days:<toolId>, the per-tool override, and only when that tool's fetcher passes its tool id into the cache layer.
2. cache_days_default, the global override written by Apply to all.
3. The lifetime the calling code passes for that specific request.
4. 86,400 seconds, one day, as the final fallback.

The resolution is deliberately forgiving. Any error, or a value that is not a number greater than zero, falls back to the caller's own lifetime. A bad configuration value can change freshness. It cannot break the cache path or change what the data says.

Reading the table#

The header shows the tool count. Section pills above it filter the table: All plus one pill per catalog section, in this order: Get Started, Site Health, Keyword & Content Research, Competitors & Backlinks, AI Visibility, Write & Optimize, Promote, Track & Report, Other.

A tool that makes no cached provider calls reads Not cached with the sub-label runs live every time, and has no lifetime select; owners still get the availability toggle in Actions. Of the 65 tools in the catalog, 31 have real cached provider lifetimes and 34 do not, because they are pure HTTP checks, live model calls, or providers that are not cached.

Built-in lifetimes are rendered in words. A tool with a single lifetime shows 1 hour, 1 day or 7 days. A tool that hits several endpoints at different lifetimes shows the span, for example 1 hour – 7 days.

Step-by-Step Guide#

Change one tool's lifetime#

1. Find the tool, using the section pills or your browser's find.
2. Open the select in Change lifetime. The first option is Default — <built-in>, followed by the presets 1, 2, 3, 5, 7, 14, 30, 60 and 90 days. If the current override is not one of those, it is added to the list.
3. Choose a value. There is no Save button. The change applies the moment you release the select.

Choosing a preset writes cache_days:<toolId> and confirms with <Tool> now caches for <n> days. Choosing the default option deletes the key and confirms with <Tool> set to built-in default. Both are audited as config.set and config.delete respectively, because the select writes through the configuration endpoint.

Change what a tool charges#

1. Find the tool and open the select in the Credits column (owners only). The first option is Default — <built-in>, followed by 0 to 20 credits. An override outside the presets is added to the list.
2. Choose a value. There is no Save button; the change applies on release and confirms with <Tool> now charges <n> credit(s) per run. Choosing the default option deletes the override and confirms with <Tool> charges its built-in cost again.

This writes tool_cost:<toolId> through the configuration endpoint, so it is audited like every other config write and takes effect within a minute at every charge site. See the key's entry in Runtime configuration for the risk notes, including the dashboard run-button labels that state built-in costs.

Apply one lifetime to every tool#

1. In the owner card at the top, type a whole number into the field labelled days. The input accepts 1 to 365.
2. Press Apply to all.
3. Confirm the browser prompt Set cache to <d> day(s) for ALL tools and remove every per-tool override?

This writes cache_days_default and deletes every cache_days: override, so nothing shadows the new global value. Success reads Applied <d> day(s) to all tools. A missing or invalid number returns the client message Enter a valid number of days., and a value outside the range returns 400 {"error":"days must be between 1 and 365"} from the server.

Take a tool out of service#

1. Find the tool and press Turn off in the Actions column (owners only).
2. Confirm the browser prompt. The tool then returns 503 This tool is temporarily unavailable. Please try again shortly. to every customer, nobody is charged, and the row shows a red OFF badge.
3. Press Turn on to put it back; that deletes the key, no confirmation.

The toggle writes tool_off:<toolId> through the configuration endpoint, so both directions are audited. Cached results can keep serving after a turn-off, so clear the tool's cached data if the stop must be immediate. Growth Actions has no toggle because its handler runs before the check; see the key's entry in Runtime configuration.

Clear cached data#

Press Clear on a row to delete that tool's cached provider rows. Success reads Cleared <n> cached row(s) for <Tool>.

Press Clear all cached data in the owner card to delete everything. The browser prompt reads Clear ALL cached provider data now? The next runs will fetch fresh (higher provider cost). Success reads Cleared <n> cached rows.

"Everything" means all nine cache tables, not just the DataForSEO rows. It used to delete from dfs_cache alone while answering all, so an operator clearing the cache to force fresh data was still served the other eight caches' stale rows with no way to tell. The response now carries a tables map with the count removed from each.

Clearing is instant and irreversible. The next run of each affected tool pays a full provider call. Clear a single tool when its data is known to be wrong; clear everything only after a provider-side data correction.

Both are audited as cache.clear, with the tool id or all as the target and <n> rows as the meta.

Where the controls do not apply#

Three cases produce a control that is absent or inert. Knowing them saves a long hunt for a setting that never took effect.

Tools that make no cached provider calls. 34 of the 65 show Not cached. There is nothing to tune and nothing to clear.

Tools that share one fetcher. Eight content tools draw their research from a single shared fetch, so a per-tool lifetime would be a dead control. Those rows show the grey text Set via Apply to all with the tooltip Shares one cached fetch with related tools — use Apply to all above. The eight are the SEO brief, article outline, article writer, content template, content optimizer, content repurposer, meta generator and press pitch tools.

Per-tool clearing needs a tagged row. Cached rows carry a tool tag only when the fetcher passed its tool id. Rows written without it can be removed only by Clear all cached data.

Cost and freshness#

Two figures on the screen matter together. The cost chip is what the customer pays in credits per run, taken from the credit table unless a tool_cost override changes it. The lifetime is what we pay the provider. Lengthening a lifetime does not change what a customer is charged; it only reduces how often we buy fresh data.

Troubleshooting#

FAQs#

Does changing a lifetime affect data that is already cached? No. Existing rows keep the timestamp they were written with, and the new lifetime is applied when their age is next checked. Shortening a lifetime therefore expires old rows immediately in effect; lengthening one does not resurrect rows that already expired.

Does clearing the cache cost the customer credits? No. Credits are charged per run, not per provider call. Clearing raises our provider bill, not theirs.

Is there a per-tool on and off switch here? No. Disabling a tool is done with the tool_off:<toolType> configuration key, typed by hand in the Config screen. See Runtime configuration.

Why do some tools cost zero credits? Because they make no paid provider or model call. They still appear in this table so the catalog is complete, and most of them read Not cached.

Where do the built-in lifetimes come from? They are the real values each tool's fetcher passes for each provider call, recorded in the worker so the screen can show the effective lifetime before any override exists. A tool with several endpoints genuinely has several lifetimes, which is why some rows show a span.