Put your SaaS metrics on your iPhone Home Screen in 2 minutes

Push any number from your app, like total accounts, paid subscriptions, or MRR, to a Home Screen or Lock Screen widget with a single HTTP request. No SDK. WidgetDash doesn’t care where the number comes from.

Before you start

• A free WidgetDash account. Sign up here
• The WidgetDash iOS app (free on the App Store, to show the widget on your phone)
• Anywhere you can make an HTTP request, like your terminal, a cron job, or your backend

1Grab your write API key

Open the dashboard and copy your WRITE key from the API Keys card. The WRITE key is how you push data and make changes, so treat it like a password. The READ key is view-only, for read-only tools or sharing a view of your numbers.

2Push your first number

A source is created automatically the first time you push to it. One request, no setup:

curl -X PUT https://api.widgetdash.app/api/v1/data/total_accounts \
  -H "Authorization: Bearer YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Total Accounts",
    "icon": "person.2.fill",
    "category": "Growth",
    "metrics": [
      { "label": "Accounts",  "value": "12,431" },
      { "label": "New today", "value": "+87" }
    ]
  }'

And paid subscriptions:

curl -X PUT https://api.widgetdash.app/api/v1/data/paid_subscriptions \
  -H "Authorization: Bearer YOUR_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Paid Subscriptions",
    "metrics": [
      { "label": "Paid subs", "value": "842" },
      { "label": "MRR",       "value": "$4,210" }
    ]
  }'

• The source_key in the path (e.g. total_accounts) is lowercase letters, numbers, and underscores. Push to the same key to update it.
• value is a string, so format it however you like: "$4,210", "12.4k", "38%".
• icon is an SF Symbol name that renders on the widget. display_name, icon, and category are optional. Leave them out and the source keeps its current values. Order is set in the app (Edit), not by pushes.

3Confirm it landed

Open Sources in the dashboard. Your sources are there with their latest values. Push again any time and they update in place.

4Add the widget on your iPhone

1. Open the WidgetDash app and connect (scan the dashboard QR, or paste your write key; a read key connects view-only).
2. Long-press the Home Screen → + → search WidgetDash → pick a size.
3. For the Lock Screen: long-press the Lock Screen → Customize → Lock Screen → tap the widget area → WidgetDash.

By default, a widget shows your sources in the order you see in the app:

• Small and the round Lock Screen widget show your first source.
• Medium and the rectangular Lock Screen widget show up to 5 sources, one headline number each.
• Large shows your sources with all their metrics, grouped by category: as many as fit, with “+N more” for the rest.

To pick what a widget shows, long-press it and tap Edit Widget. Choose a Source, then add more under More Sources (Medium, Large and the rectangular Lock Screen widget); they show in the order you pick. Each widget can show different sources, and All Sources goes back to the default. Several sources need iOS app 1.7 or later.

To change the order, tap Edit in the app: move sources up or down, or tap the eye to hide a source from the widgets on this iPhone.

5Automate it

Point a small script at your database and run it on a schedule. Python:

import requests, psycopg2

WRITE_KEY = "YOUR_WRITE_KEY"
BASE = "https://api.widgetdash.app/api/v1/data"

conn = psycopg2.connect("postgresql://user:pass@host/db")
cur = conn.cursor()
cur.execute("SELECT count(*) FROM users")
accounts = cur.fetchone()[0]
cur.execute("SELECT count(*) FROM subscriptions WHERE status = 'active'")
paid = cur.fetchone()[0]

def push(key, display, icon, metrics):
    requests.put(f"{BASE}/{key}",
        headers={"Authorization": f"Bearer {WRITE_KEY}"},
        json={"display_name": display, "icon": icon, "metrics": metrics}, timeout=10)

push("total_accounts", "Total Accounts", "person.2.fill",
     [{"label": "Accounts", "value": f"{accounts:,}"}])
push("paid_subscriptions", "Paid Subscriptions", "creditcard.fill",
     [{"label": "Paid subs", "value": f"{paid:,}"}])

Run it every 15 minutes with cron:

*/15 * * * * /usr/bin/python3 /opt/scripts/push_widgetdash.py

More recipes

You want to see…	source_key	Metrics
Total accounts	total_accounts	Accounts
Paid subscriptions	paid_subscriptions	Paid subs, MRR
Signups today	signups_today	Today, vs yesterday
Active trials	active_trials	On trial, conversion %
Stripe MRR	mrr	MRR, growth %

Prefer no code? Use a pre-built source

The Catalog (called Free Sources in the iPhone app) has ready-made sources that update themselves. One click to add, no scripting:

• Finance: Bitcoin Price, Ethereum Price, Crypto Market (market cap and BTC dominance), Fear & Greed Index, EUR/USD Rate, and Travel Currency, where you pick any two of 39 currencies (set it up in the iPhone app).
• Science: People in Space.
• Fun: Random Quotes, Cat Facts, Dad Jokes, Chuck Norris Facts, Useless Facts.

Catalog sources count toward the free plan's 5 sources, the same as sources you push.

Metric types and colors

Each metric can have a type, which changes how it looks, and a color:

number	A big, bold number.
text	Plain text (the default when you leave type out).
status	A colored badge, such as OK or Down.
progress	A bar, with value from 0 to 100.
timestamp	A time (ISO 8601 or Unix seconds) shown as “5m ago” and kept current between pushes.

Colors: green, red, yellow, blue, gray, orange, purple, cyan. To pick a color from the value, send color_rules once and they stay until you replace them. For example, a backup timestamp that turns yellow after 3 days and red after 7:

"color_rules": {
  "Last backup": [
    { "older_than": "7d", "color": "red" },
    { "older_than": "3d", "color": "yellow" },
    { "color": "green" }
  ]
}

Rules can also use below, above and equals. See metric types and color rules for the full details.

On a Large widget, text that shares a row with other metrics shows up to two lines. For a long value, such as a title, add "wide": true to the metric and it gets a full row of its own (iOS app 1.8 or later). Put wide metrics last to keep the others together.

Go live: real-time on the Lock Screen & Dynamic Island PRO

Live Activities turn a source into a real-time card on the Lock Screen and in the Dynamic Island. While a source is live, every data push updates the card instantly — no widget refresh delay. Perfect for launch days, deploys, incident dashboards, or watching a metric you care about right now.

Requirements: Pro plan · iOS 17.6 or later. Live Activities are rolling out gradually to Pro accounts.

How to use it:

1. Enable	Open the WidgetDash iOS app once and allow Live Activities when prompted. This also registers your device for remote starts.
2. Go live	Tap Go Live on any source in the app — or use Start on my iPhone from the web dashboard.
3. Watch it update	Keep pushing data as usual. Each change lands on the card within seconds (updates are spaced ~15s apart to respect iOS budgets).
4. End it	Swipe the card away, end it from the app or web — or let iOS end it automatically (activities run up to ~8h, staying on the Lock Screen up to ~12h).

Buses and trains in Israel: a ready-made Live Activity that counts down to when you should leave, then follows your bus and train. The step-by-step setup saves your trips and gives you shortcuts to start and stop it.

Live Activities are for ongoing sessions, not a permanent dashboard — iOS ends them after a few hours by design. For always-on numbers, the regular Home/Lock Screen widgets are the right tool.

Use it from an AI assistant (MCP)

With the official WidgetDash MCP server, Claude, Cursor and other MCP clients can put numbers on your widget and read them back for you, with the tools push_number, push_metrics, get_widget_data, list_sources and delete_source. In Claude Code:

claude mcp add widgetdash -e WIDGETDASH_WRITE_KEY=your-write-key -- npx -y widgetdash-mcp

For Claude Desktop, Cursor and other clients, see the setup in the README. The write key lets the assistant change your widget data, so only give it to assistants you trust.

API reference

Push data	PUT https://api.widgetdash.app/api/v1/data/<source_key>
Auth	Authorization: Bearer <WRITE_KEY>
Body	{ "display_name", "icon", "category", "metrics": [ { "label", "value", "type", "color", "wide", "icon" } ], "color_rules" }
source_key	^[a-z0-9_]+$. Push to the same key to update
Limits	Free: up to 5 sources · Pro: unlimited. Rate limit: 120 req/min.
Read data	GET /api/v1/widget with Authorization: Bearer <READ_KEY>
Full reference	All endpoints and llms-full.txt

FAQ

Do I have to create the source first?

No. The first PUT to a new key creates it automatically. Same key again = update.

Does it work with my stack?

Yes. It’s just an HTTP request. Postgres, MySQL, Mongo, Stripe, a webhook, a shell one-liner, anything that can make a PUT. WidgetDash never connects to your database. You push the final number.

What data do you store?

Only what you send: labels and values, plus the source name/icon. No DB credentials, no PII unless you put it in a value. Keep the write key secret.

How often does it refresh on the phone?

Push as often as you like (within 120 req/min). Widgets ask iOS for a refresh about every 5 minutes on every plan, and iOS decides exactly when to repaint them. For updates within seconds, use a Live Activity (Pro). Pushing every 5 to 15 minutes is plenty for most metrics.

Read key vs write key?

Write = push data and make changes, such as deleting a source (keep secret; the dashboard QR code includes it, so only scan it on your own phone). Read = view only: it can show your data but never change it, so it suits read-only tools. If a key leaks, use Rotate Keys in the web dashboard to replace both keys, then scan the new QR code on your iPhone and update your scripts.

Can I show it on the Lock Screen?

Yes. Rectangular and round Lock Screen widgets are supported, and each one can show the sources you choose with Edit Widget (the round one shows one, the rectangular one up to four). Pro users can additionally go live with real-time Live Activities.

How fast do Live Activities update?

Each data push lands on the card within seconds. Consecutive updates are spaced about 15 seconds apart to respect iOS push budgets, and unchanged values aren't re-sent.

Does WidgetDash send notifications?

Only if you turn them on in the iPhone app. They're occasional updates from WidgetDash, such as new features, and you can turn them off any time in the app or in iOS Settings. Alerts based on your own numbers aren't available yet. Use color rules to make a number turn red on the widget instead.

How do I delete my account?

In the iPhone app, scroll to Account and tap Delete Account. On the web, open Account and choose Delete account. It's immediate: your sources and data are deleted, and a Pro subscription is cancelled. See the privacy policy for details.

What does it cost?

Free for up to 5 sources. Pro is $4.90/mo (or $29.90/yr) for unlimited sources and Live Activities.

Is there an Android version?

Not yet. WidgetDash is iOS-only today.