Provenance
Every row carries source, fetched_at, and freshness_days. That's the whole model.
LinkFetch ships provenance on every response. It's not a feature — it's the contract. If you can't explain where your data came from, you can't ship agent workflows to a regulated customer. We give you the audit trail by default.
The meta.provenance object
Every endpoint response has this shape:
{
"data": { "...": "..." },
"meta": {
"request_id": "req_2Yq7zR1tDkH",
"credits_charged": 5,
"provenance": {
"source": "extension",
"fetched_at": "2026-04-23T14:02:11Z",
"freshness_days": 6
}
}
}source
Which pipeline produced the row. Values:
| Source | Meaning |
|---|---|
extension | Ingested through the end user's own LinkedIn session via our Chrome extension. User is principal. |
linkedin_guest | Fetched from a public-guest LinkedIn page — no login, just what a logged-out visitor sees. |
cache | Served from LinkFetch's cache (never older than the tier TTL). |
fetched_at
ISO-8601 timestamp (UTC) of when the underlying record was captured. For cached rows this is the original capture time, not the cache hit time.
freshness_days
Integer: how many days have passed since fetched_at. Zero means fetched
today. Your agent can decide whether to re-fetch.
Freshness policy
LinkFetch caches responses per endpoint:
| Endpoint | TTL | Re-fetch on miss |
|---|---|---|
/v1/profiles | 30 days | Through the end user's session |
/v1/companies/:slug | 14 days | Guest page |
/v1/jobs | 1 hour | Index refresh every 24h |
/v1/people/search | 15 minutes | No cache for filtered searches |
You can override with ?fresh=true to force a refetch. That charges full
credits; a cache hit is the default cost.
Audit trail
Every request is logged with:
request_idreturned in the response +X-Request-Idheader- Endpoint, params, status, duration, credits charged
- Which key was used
- Which source served the data
Accessible in the dashboard or via a dedicated audit export (email info@linkfetch.io for the audit endpoint).
Why we do it this way
The alternative — opaque data with no source stamp — is how every major LinkedIn vendor before us operated. It's also why their compliance stories collapsed under enforcement. Provenance is cheap; pretending you don't have to care is expensive.