Favicon API
Reference

Authentication

The favicon API authenticates requests using a Bearer token. Pass your API key in the Authorization header or as a ?key= query parameter.

Authorization: Bearer fav_live_your_key_here

# or as a query param (useful for quick tests):
?key=fav_live_your_key_here

Generate API keys in your dashboard.

Usage, billing & security

Your API key identifies your account. The url parameter (and the domain we derive from it) only tells us which website's favicon to fetch — it does not identify who is calling the API. Two different customers requesting the same domain are distinguished solely by their keys.

What counts toward your quota

Each successful HTTP response from the favicon API (HTTP 200 with a JSON body) counts as one call toward your monthly limit. That includes responses served from our CDN cache (when cached: true) — the API still authenticated you and returned a valid result.

Billing period

Quotas reset each calendar month (e.g. 2026-04). If you upgrade mid-month, your plan tier updates for access and limits; your subscription invoice period from Stripe may not align exactly with the calendar month used for API quotas — see your dashboard for current usage.

Usage history retention

Per-call usage rows in our systems are retained for a limited time (on the order of months) for operational dashboards and support. They are not intended as a permanent legal or accounting ledger; keep your own records if you need long-term audit trails.

Stripe & plans

Stripe webhooks update your subscription plan and status on your account. Per-call API usage is not automatically reported to Stripe as metered billing for invoicing — quota enforcement and usage counts are enforced in the FaviconAPIs app from your plan and usage records.

Don't expose your key in <img src>

Putting your API key in a browser-visible URL (for example ?key= in an <img src>) can leak the secret via the Referer header to any third-party server that loads the image. Prefer calling the API from your server or a backend proxy you control, then pass only the returned CDN image URL (or your own cached URL) to the client. See also our migration guide from Google's favicon URL.

Plans & monthly limits

When your limit is reached, the API returns HTTP 429 with details in the JSON body. Upgrade anytime →

Endpoint

Query parameters

Response format

All responses are application/json. A successful favicon API response includes:

{
  "url":        "https://cdn.faviconapis.com/favicons/github.com.png",
  "domain":     "github.com",
  "width":      256,
  "height":     256,
  "format":     "png",
  "sourceType": "svg",
  "cached":     true,
  "cachedAt":   "2026-03-01T09:00:00.000Z"
}

Source types

The favicon API tries each source in priority order, stopping at the first successful fetch. The sourceType field tells you which source produced the favicon.

Error codes

Code examples

curl "https://faviconapis.com/api/v1/favicon?url=https://github.com" \
  -H "Authorization: Bearer fav_live_your_key_here"

const res = await fetch(
  "https://faviconapis.com/api/v1/favicon?url=https://github.com",
  { headers: { Authorization: "Bearer fav_live_your_key_here" } }
);
const { url, width, sourceType, cached } = await res.json();

import requests

response = requests.get(
    "https://faviconapis.com/api/v1/favicon",
    params={"url": "https://github.com"},
    headers={"Authorization": "Bearer fav_live_your_key_here"},
)
data = response.json()
print(data["url"])   # CDN URL to the 256px PNG

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
    "https://faviconapis.com/api/v1/favicon?url=https://github.com");
curl_setopt($ch, CURLOPT_HTTPHEADER,
    ["Authorization: Bearer fav_live_your_key_here"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
echo $data["url"];

Caching

FaviconAPIs caches processed favicons in DigitalOcean Spaces CDN for 7 days. When you call the favicon API for a domain that was fetched within the last 7 days, the cached CDN URL is returned immediately — typically in under 30ms. After 7 days, the favicon is re-fetched, re-processed, and the cache is updated. Cached responses include a cachedAt timestamp and "cached": true in the response.