When to bypass the enrichment cache

A cache hit costs one credit. A forced fresh read costs one credit. The price is identical, so the decision to send use_cache=false is never about money. It is about one thing: whether you need a guaranteed read at source, or whether a stored copy is already the same bytes.

Most of the time it is the same bytes, and the fresh read is waste. Here is how to tell the two apart.

What use_cache actually toggles

use_cache is a boolean query parameter that defaults to true. Leave it on and a repeat lookup within 24 hours is served from the store: instantly, and without a call to the data source. Set it to false and you skip that store and force a genuine re-read at source.

GET /v1/people/profile?entity_urn=ACoAAB1xExample&use_cache=false

The subtle part is why the default is safe. The 24 hour window is not arbitrary: it matches the cache the data source itself runs. Inside that window a “fresh” fetch would return the identical payload the source already holds, so leaving the cache on costs you nothing in freshness. This is the same cache and billing contract that makes a stored hit cost a full credit: same data, delivered faster.

A live response is not a promise of fresh data

This is the fact that makes the decision worth writing down. Because the store window matches the source’s own cache, a response marked live can still carry data the source cached up to 24 hours earlier.

X-Data-Source: live
X-Fetched-At: 2026-09-05T08:14:22Z
X-Data-Age-Seconds: 3
X-Credits-Charged: 1

X-Data-Age-Seconds: 3 here means Triguna read it three seconds ago. It does not mean the underlying record changed three seconds ago. X-Data-Age-Seconds measures how long ago the retrieval happened, not how old the data behind it is. That distinction, and every other header on the response, is laid out in how to read the provenance headers.

So retrying a lookup, or re-running a pipeline an hour later, does not buy you fresher data. The only control that guarantees a real read at source is use_cache=false. Everything else returns a copy.

When a source read is worth sending

Send use_cache=false when you have a specific reason to believe the stored copy is behind the world, and the decision the record drives cannot tolerate that gap:

You were told about a change out of band. A funding round, an acquisition, or a job change reached you through news or a customer before your refresh window rolled over. You know the store is stale for this one record.
You have to attest to a source read. A compliance or audit path where “we read this at the source at this timestamp” is the claim you need to make, and a stored copy will not satisfy it.
You are debugging a suspected stale record. A single forced read tells you whether the store or the source is the thing that is behind.

All three share a shape: a named, specific record where you already have reason to doubt the copy. That is the opposite of a blanket policy.

When it is waste

Sending use_cache=false on every call is the most expensive habit available, and it buys nothing the default did not already give you inside the window. Skip it when:

You are backfilling. A nightly backfill re-reads records in bulk. Forcing a source read on each one doubles the work at the source for data that has not moved. Pace against the window, not against the source.
You are inside the field’s natural decay. A job title changes every one to three years; a company’s headcount moves quarterly. Re-reading a record you fetched last week gives you the same value at the same price. Set the cadence per field, the way how often to re-enrich a record lays out, and let the default cache serve everything inside it.
You just want to confirm what you have. If the question is “what does the store hold for this entity”, that is the default. use_cache=false answers a different question, and charges the same to do it.

Confirm the read actually happened at source

Sending the parameter is not proof it was honored. Read the header back:

const res = await fetch(
  'https://api.triguna.ai/v1/companies/details?company_id=stripe&use_cache=false',
  { headers: { ApiKey: process.env.TRIGUNA_API_KEY } }
);

const source = res.headers.get('X-Data-Source'); // expect 'live'

if (source === 'stale_fallback') {
  // The source was failing, so a stored copy came back instead of an error.
  // Your forced read did not reach source; the data is of unknown age.
  queueReread('stripe');
}

A use_cache=false request that returns stale_fallback is telling you the source was down and a stored copy was served rather than an error. That is the API degrading instead of failing, which is usually what you want, but it means the one thing you asked for, a source read, did not happen. Branch on it.

The full behavior lives in the caching and freshness reference, and the reasoning behind serving provenance on every response is part of how Triguna is built. You can watch these headers change on real calls with the five free credits from signup.

Why a cache hit still costs a credit explains the contract this decision sits on top of.
How often should you re-enrich a record? sets the cadence that keeps use_cache=false out of your hot path.
Provenance lives in the headers is how you confirm what any single read actually returned.
The Person API and Company API both accept use_cache on every call.

cachingfreshnesspractices

A fresh read and a cache hit cost the same credit: when to send use_cache=false