How CloudPeek works · CloudPeek docs

From CloudWatch to your Home Screen

A widget definitionA widget on a CloudWatch dashboard, a preset, or one an AI model wrote: CloudWatch's own JSON, saying which metrics or alarms, and how to show them.

Data from CloudWatchFetched from the widget's account with its own sign-in, straight from your device to AWS.

A snapshotThe values, ready to draw, kept on your device. The Home Screen widget draws it at every size.

Each time a widget refreshes, CloudPeek:

Reads the dashboard again, for a widget from a dashboard (GetDashboard), and finds the widget in it, so edits in the console or from code show up. Presets and AI widgets keep their definition with the widget, so they skip this.
Works out the queries the way the CloudWatch console does: time range, period, metric math, SEARCH, and each metric's region. See the Widget reference.
Fetches the data with one GetMetricData request for each region the widget uses, in parallel. Alarm widgets call DescribeAlarms in each alarm's region instead.
Saves a snapshot on your device, in storage only the app and its widgets can read, and the widget draws it.

There's no CloudPeek server in between: see What leaves your device.

When widgets refresh

On a schedule: every 30 minutes by default. Change it in Settings, under Home Screen Widgets, with Refresh: every 15 or 30 minutes, or every 1, 2 or 6 hours. iOS decides exactly when, based on how often you look at your widgets, and spreads refreshes out on a busy day or in Low Power Mode, so treat it as a guide.
Whenever you open CloudPeek.
When you ask: the refresh button on a medium or larger widget, pulling down on the Widgets tab, Refresh in a widget's More menu, or Refresh Widgets Now in Settings.

Data loaded in the last five minutes, by the app or by another widget, is reused rather than fetched and billed again, unless you've asked for a refresh or a refresh has failed since.

When a refresh fails

The widget keeps its last data and says why and how old it is: “Sign-in expired · data from Fri 14:05” on medium and large widgets, or “Not updated since 14:05” on small ones.
Data more than a day old fades, so it can't pass for current.
After a network or AWS hiccup, a widget with recent data tries again within 10 minutes. Other failures, such as a sign-in that ended, wait for the next scheduled refresh: they need you to do something first.
After your iPhone restarts, widgets can't read your sign-ins until you first unlock it. They try again every few minutes at first, then less often.

Every message, and what to do about it, is in Troubleshooting.

What it costs

CloudPeek is free. What it asks AWS for is billed to your AWS account, at CloudWatch's usual prices:

What	AWS charges
Each refresh of a metric widget: one `GetMetricData` request per region	$0.01 per 1,000 metrics requested. A widget with 5 metrics refreshing every 30 minutes requests about 7,200 a month: about 7 cents.
Each refresh of a dashboard widget also reads its dashboard (`GetDashboard`); alarm widgets call `DescribeAlarms` instead of `GetMetricData`	API requests, priced separately from metrics. See CloudWatch pricing.
Dashboards you create	The first three are free; after that, $3 a month each. Presets and AI widgets need no dashboard.
Writing an AI widget, once	About a cent in Amazon Bedrock, billed to the account; or a few cents with Claude Sonnet 5.5, billed to your Anthropic account. See AI widgets.

To keep an eye on it, add the GetMetricData calls preset: it graphs your account's GetMetricData calls each hour.

When a dashboard changes

Widgets from a dashboard follow it: they find their widget again after it's moved, resized, retitled or edited, and keep their last version if it can't be found. How changes reach your phone has the details.