Docs/Concepts/How it works

How it works

Every Avtrz URL goes through the same four-stage pipeline. The first request finds a photo. Every later request to the same profile is a CDN hit. Below, the pipeline.

The pipeline

Step 1

Match the profile

The LinkedIn URL or username is normalized and resolved against our directory of business profiles.

Step 2

Decode the photo

Source image is fetched and face-aware square-cropped so the subject stays centered at every size.

Step 3

Encode for the client

The crop is encoded to the format and size your client asked for — WEBP or PNG, 32 through 512 pixels.

Step 4

Cache 24 hours

The response is pinned on the CDN with Cache-Control: public, max-age=86400. Subsequent hits return in single-digit ms.

Where the photos come from

Avtrz resolves a LinkedIn profile (by full URL or by username) and serves the profile photo associated with it. We don't scrape personal social, we don't pull from inboxes, and we don't use photos the person didn't choose as their profile image.

Fallbacks

When we can't resolve a profile, the endpoint returns a deterministic SVG fallback at the size you requested. The fallback is a soft monogram on a stable background: visually consistent across a list and easy to swap with your own avatar component if you prefer.

Cache strategy

Two layers, both opaque. You don't need to set headers or invalidate anything (the contract below handles every edge case).

Name	Type		Description
CDN cache	edge	Optional	Successful redirects ship `Cache-Control: public, max-age=86400`. The browser, your CDN, and intermediate proxies all reuse the response for 24 hours.
Fallback responses	edge	Optional	SVG fallbacks ship `Cache-Control: no-store` so a transient miss can't pin a placeholder in your CDN.
Profile cache	origin	Optional	Resolved profile → photo mapping is cached server-side. The first hit warms the cache for everyone else in your workspace.
Billing	meter	Optional	Every request meters `avatar_requests`. The first lookup of a new profile also meters `avatar_new_profiles`.

The data path, end to end

For the privacy team's spreadsheet: what Avtrz sees, what it stores, and what it doesn't.

Name	Type		Description
LinkedIn URL / username	in transit	Optional	TLS only. Used to resolve the profile. Not used for anything else.
Resolved profile	stored	Optional	The matched LinkedIn profile and its photo URL. Cached server-side so subsequent requests don't re-resolve.
Your IP / referer	logged	Optional	Standard request log. Used for abuse detection and your usage chart.

Authentication

Get avatar