Docs
Your first chart URL in three steps
No SDK, no signup: a chart is a URL that returns a PNG. Everything below works with a plain curl, an <img> tag or any HTTP client.
1. Build the URL
Start with the endpoint and add legacy parameters:
https://urlchart.com/chart?cht=bvg&chs=400x200&chd=t:10,40,80&chxt=y
cht=bvg is vertical grouped bars, chs=400x200 the image size, chd=t:… the data and chxt=y one y axis. Open it in a browser tab and you have the image.
2. Add a key when you need production limits
Without a key you get the free tier: watermarked, 60 requests/minute, 1,000 unique renders per month. With a paid subscription you get a key; add it as a query parameter (or send it as a bearer token):
https://urlchart.com/chart?cht=bvg&chd=t:10,40,80&key=uc_live_…
The key is removed from the origin request and from the cache key, so a paid and a free request for the same chart are the same chart with different watermark variants. If a key is malformed or revoked you get 401 JSON — a broken key is an error you can see, not a silent watermark.
3. Embed it
<img src="https://urlchart.com/chart?cht=bvg&chd=t:10,40,80"
width="400" height="200" alt="Quarterly signups">
Set width and height to chs so the page does not reflow. That is the whole integration.
Cache behaviour
- Successful renders are immutable for one year:
Cache-Control: public, immutable, max-age=31536000. Browsers and the edge hold the bytes. - The query string is the chart's identity. Two URLs with the same parameters (in any order) are the same image; changing a rendered parameter produces a new URL and a new render.
- Cache-bust parameters (
_,cb,cachebust,t) are stripped before rendering and before keying. They cannot be used to bust the cache, and they never create a second render — that is intentional, so timestamped embeds do not inflate usage. - Cached hits are not metered. If you need to change a chart, change the data in the URL; if you need to invalidate an image that is already in someone's browser cache, the URL has to change.
Errors and limits
200 image/pngfor every URL whose data decodes — including URLs with unknown or invalid parameters (they degrade and are reported).400 JSONonly when thechdpayload cannot be interpreted at all. Never an error image.401 JSONfor a malformed, unknown or revoked API key.429 JSONwithRetry-Afterfor rate limits and the free monthly cap.X-UrlChart-Metaon successful renders carries the parsed axes, series-to-axis assignment, and the degraded/ignored/unsupported lists. It is the same data the tester shows.
JSON charts
POST /chart also accepts a Chart.js configuration body and returns a PNG. That path is for callers who already hold Chart.js JSON; the legacy parameter endpoint above is the compatibility surface. POST /gchart is rejected — /gchart is GET-only by contract.
Next: legacy parameter reference · Drop-in Tester · Pricing