Authentication, rate limits and pricing

Keyless and keyed access

• REST reads — summary, series, statements, charts, the OpenAPI document — are keyless and CORS-open on the free tier, governed by edge fair-use rules and the chart render limiter.
• MCP tools/call is the one keyed lane (its responses cannot be edge-cached). The free tier works there; discovery methods stay keyless.
• A key adds exact per-account metering, tier quotas, X-RateLimit-* headers, and paid tiers — on every endpoint. A presented key that is malformed, unknown or revoked answers 401; it is never silently downgraded to anonymous.

API keys

Mint keys in the developer console at /developers/keys (sign-in required). Keys look like tgm_live_ followed by 40 hex characters, are shown once at creation, and are stored hashed. An account holds up to 5 active keys; quotas are per account, so rotating or adding keys never multiplies a tier's allowance. Revocations and tier changes take effect within about a minute.

Send the key as Authorization: Bearer tgm_live_… or as an x-api-key header. Keyed responses are Cache-Control: private, max-age=3600 — they bypass the shared edge cache so accounting is exact.

curl -s -D - https://tgmcharts.com/api/v1/summary/AAPL \
  -H "Authorization: Bearer tgm_live_YOUR_KEY"

curl -s https://tgmcharts.com/api/v1/series/KO/dividend-yield?years=5 \
  -H "x-api-key: tgm_live_YOUR_KEY"

Request units

Quotas are counted in request units, weighted by what a request costs to serve.

Tiers and pricing

Prices are monthly list prices in US dollars. Upgrades are started from the developer console at /developers/keys; if checkout is not yet open for your account, the console says so and the contact page waitlist (mention "API waitlist") gets you in first.

• Free: 1,000 units per day with or without a key, attribution required, chart renders carry the TGMCharts frame; commercial use at this volume is allowed under the API terms.
• Keyless free use is governed by edge fair-use limits rather than exact metering; a free key gives you exact accounting and headers.
• Scale is the metered tier: its cap is soft, and units past 10,000,000 per month are billed at $0.10 per 1,000 units rather than refused.

Rate-limit headers

401 and 429 bodies

Error bodies are JSON, Cache-Control: no-store, CORS-open. The upgradeUrl and docs fields point at the console and this page.

{
  "error": "Invalid API key",
  "reason": "Unknown API key.",
  "docs": "https://tgmcharts.com/developers/docs/authentication-and-limits"
}

{
  "error": "free tier daily quota reached (1000 units). Upgrade at https://tgmcharts.com/developers/keys or retry after the window resets.",
  "tier": "free",
  "upgradeUrl": "https://tgmcharts.com/developers/keys",
  "docs": "https://tgmcharts.com/developers/docs/authentication-and-limits"
}

{
  "error": "Render rate limit reached — cached chart URLs are unlimited; new renders are capped per minute. API keys lift this to tier quotas: https://tgmcharts.com/developers/keys",
  "upgradeUrl": "https://tgmcharts.com/developers/keys",
  "docs": "https://tgmcharts.com/developers/docs/authentication-and-limits"
}

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "tools/call requires an API key — the free tier works (no card): mint one at https://tgmcharts.com/developers/keys and send it as Authorization: Bearer tgm_live_… . Lifecycle methods (initialize, tools/list, ping) need no key."
  }
}

Attribution and use

• Name TGMCharts as the data source and link to tgmcharts.com wherever API data or charts are displayed ("data by TGMCharts"). Chart images carry the attribution in the frame; do not remove, obscure or crop it.
• Do not redistribute or resell API data in bulk or as a standalone dataset or feed, and do not circumvent limits or access controls. Full text: Terms §19, API Terms.
• Please cache: data changes at most daily, and every endpoint sends cache headers that do this for you.