How do I embed a progress bar in my GitHub README?

Use the SVG format: ![Progress](https://api.gru0.dev/progress/v1/year?format=svg). Replace 'year' with 'day' or use custom value/max parameters.

Can I use custom values instead of date-based progress?

Yes! Pass ?value=847&max=1000 for any custom metric. Date ranges with ?start=&end= are also supported via the same endpoint.

What output formats are available?

Six formats: text (raw number), ascii (unicode bar, 6 styles), svg (vector image), json (structured data), element (web component), iframe (embeddable frame).

Is the progress bar timezone aware?

Yes. Pass any IANA timezone via ?tz=. Falls back to proxy headers (auto-detected from IP), then UTC.

Does it work with Notion or other sites?

Yes. Use the script tag embed for any HTML page including Notion embeds, or use the SVG/img format for markdown-based platforms.

Can I customize the colors and appearance?

Yes. Set color and bg attributes on the web component element, or pass ?color=&bg= for SVG images. Any valid CSS color is supported.

Progress Bar API, live progress bars for READMEs, sites & apps

// reference

Endpoints & parameters

Data endpoints plus the hosted progress store and web component script.json is shaped for the component, use text, ascii, or svg for direct consumption. SVG defaults to light mode. Pass dark=true for dark mode or dark=false to stay on light.color and bg work with either mode.

GET/progress/v1

Main, requires ?value=&max=

GET/progress/v1/day

Demo, current day progress

GET/progress/v1/year

Demo, current year progress

GET/progress/v1/multi

POST/progress/v1/store

Create a hosted progress bar, returns { id, writeKey, badgeUrl }

PATCH/progress/v1/store/{id}

Update a bar, requires Authorization: Bearer <writeKey>

GET/progress/v1/store/{id}

Render a stored bar (public, all formats)

DELETE/progress/v1/store/{id}

Delete a bar, requires Authorization: Bearer <writeKey>

GET/progress-bar.js

Web component script

curl

curl "https://api.gru0.dev/progress/v1?value=847&max=1000"
# → 84.70

namevaluesdefault

valueNon-negative number,

maxPositive number,

unitShort label (max 32 chars),

tzAny IANA timezone, auto-detected via headerproxy header → UTC

formattext · ascii · json · svg · element · iframeelement

styleblocks · shades · dots · arrows · line · mosaicblocks

decimals0, 60

width10, 20040

showpct · value · both · nonepct

labelCustom text (max 64 chars)generated

colorBar accent (any CSS color, SVG + element, global for multi)#6366f1

bgCard background (any CSS color, SVG + element)#f8fafc

darkDark mode (true/1) or light (false/0), SVG + iframefalse (light)

compactMinimal layout, removes card wrapper,

no-cardRemoves card background/shadow,

srcCustom JSON endpoint URL,

refreshPolling interval in seconds (1,300)60

barsPipe-separated bar definitions: Label:value:max[:color] (max 6 bars)required for /multi

web component

The element format uses the <progress-bar> custom element. It loads JSON from the API and renders inside closed Shadow DOM, no site CSS can leak in.

Adapts to any theme: reads CSS custom properties (--primary, --accent, --card, --surface, --foreground, --radius, --font-mono, and more) so it blends into any site by default. Use color / bg attributes to override.

element

<script src="https://api.gru0.dev/progress-bar.js" defer></script>
<progress-bar value="847" max="1000" label="Sprints" unit="tasks"></progress-bar>

Attributes: value, max, label, unit, tz, day, year, color, bg, compact, no-card, src (custom JSON URL), refresh (polling seconds, 1,300).

day, year, and date-range modes update the percentage in real time every second using client-side interpolation. Custom src endpoints use the refresh interval for polling.

fetching…