Cache and budgets

Result cache

When the same lookup (same tool, input and options) was done recently, the app reuses that result instead of calling Tomba again. It is instant and free: no API call, no credit, no charge.

• Results are reused for 30 days by default (setting cache_days, 0 to 365; 0 turns the cache off).
• Cached rows have SOURCE = 'cache' in the output table, and single lookups return "source": "cache".
• Only real answers are cached (found and not_found). Errors are always retried.

Code
CALL TOMBA.core.set_setting('cache_days', '7');      -- app_admin
CALL TOMBA.core.clear_cache('email_verifier');       -- app_admin; '' clears every tool

Lower cache_days when freshness matters, for example for email verification before a campaign.

Credit limit per run

Add max_credits to a run's options. The run is sized so it never goes over: it stops before a batch of rows could exceed the limit, with status PARTIAL.

Code
CALL TOMBA.core.run_tool('domain_search', 'CRM.PUBLIC.ACCOUNTS', {'domain': 'WEBSITE'}, 'ACCOUNT_EMAILS', 10000,
                         {'emails_per_domain': 20, 'max_credits': 5000});

The limit counts the worst case per row (for example 2 credits per domain for 20 emails, or +5 per phone with enrich_mobile), so the actual spend is usually lower. Resume the run to continue past the limit.

Monthly budget

Cap all runs in a calendar month (UTC), in Tomba credits:

Code
CALL TOMBA.core.set_setting('monthly_credit_budget', '100000');   -- app_admin; 0 = no limit

When the budget is reached, runs stop as PARTIAL and resume automatically when the next month starts. The Overview page of the Streamlit app shows how much of the budget is used.