Protocol
Timelines and refreshes
iOS decides when a widget fetches new data. You cannot start a fetch on demand. Use timelines for future states that you know, and timers for anything based on the clock.
How refreshes work
refresh is the earliest time at which you want the next fetch. It is a request
to iOS, not a schedule. iOS decides when each fetch happens, and that is some time after
the time you asked for.
iOS manages a refresh budget for each widget. You cannot see the budget, and you cannot use it faster. If a widget asks too often, iOS grants a smaller share of the fetches that it asked for. Return payloads that stay correct between fetches.
Entries
An entry is a view with a time. If you send several entries, the phone renders each entry at its time. The phone does not contact your server again.
{
"v": 1,
"refresh": 3600,
"entries": [
{"at": "2026-08-11T09:00:00Z", "view": {"type": "text", "text": "Platform 3"}},
{"at": "2026-08-11T11:30:00Z", "view": {"type": "text", "text": "Platform 7"}},
{"at": "2026-08-11T14:00:00Z", "view": {"type": "text", "text": "Platform 3"}}
]
} Put everything that you know at request time into the timeline. Examples are a calendar that you have already fetched, a train schedule, a shift rota and a countdown to a fixed date. The next fetch brings the data that you cannot predict.
{
"v": 1,
"preferredFamily": "systemLarge",
"refresh": 3600,
"accessibility": "Four meetings today, next is standup at 9",
"entries": [
{
"at": "2026-08-11T09:00:00Z",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 10,
"padding": 16,
"bg": "white",
"children": [
{
"type": "hstack",
"children": [
{
"type": "vstack",
"align": "leading",
"spacing": -2,
"children": [
{
"type": "text",
"text": "TUESDAY",
"style": "caption2",
"weight": "bold",
"color": "red"
},
{
"type": "text",
"text": "11",
"size": 32,
"weight": "regular",
"color": "primary"
}
]
},
{"type": "spacer"},
{
"type": "text",
"text": "4 to go",
"style": "caption",
"weight": "semibold",
"color": "secondary"
}
]
},
{
"type": "text",
"text": "NOW",
"style": "caption2",
"weight": "bold",
"color": "blue"
},
{
"type": "hstack",
"spacing": 10,
"w": "fill",
"padding": 10,
"bg": "blue/12",
"corner": 10,
"children": [
{"type": "rect", "w": 4, "fill": "blue", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 2,
"children": [
{
"type": "text",
"text": "Standup",
"style": "title3",
"weight": "semibold",
"color": "primary",
"lines": 2
},
{
"type": "text",
"text": "09:00 – 09:15",
"style": "subheadline",
"weight": "medium",
"color": "blue",
"monoDigits": true
},
{
"type": "text",
"text": "Team sync · Zoom",
"style": "footnote",
"color": "secondary",
"lines": 1
}
]
},
{"type": "spacer"}
]
},
{
"type": "text",
"text": "LATER",
"style": "caption2",
"weight": "bold",
"color": "tertiary"
},
{
"type": "vstack",
"align": "leading",
"spacing": 6,
"overflow": "drop",
"more": {
"type": "text",
"text": "+{count} more",
"style": "caption",
"color": "secondary"
},
"children": [
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "purple", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "Design review",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "11:30",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
},
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "teal", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "1:1 with Alex",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "14:00",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
},
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "Sprint 42 retro",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "16:30",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
}
]
},
{"type": "spacer"}
]
}
},
{
"at": "2026-08-11T11:30:00Z",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 10,
"padding": 16,
"bg": "white",
"children": [
{
"type": "hstack",
"children": [
{
"type": "vstack",
"align": "leading",
"spacing": -2,
"children": [
{
"type": "text",
"text": "TUESDAY",
"style": "caption2",
"weight": "bold",
"color": "red"
},
{
"type": "text",
"text": "11",
"size": 32,
"weight": "regular",
"color": "primary"
}
]
},
{"type": "spacer"},
{
"type": "text",
"text": "3 to go",
"style": "caption",
"weight": "semibold",
"color": "secondary"
}
]
},
{
"type": "text",
"text": "NOW",
"style": "caption2",
"weight": "bold",
"color": "purple"
},
{
"type": "hstack",
"spacing": 10,
"w": "fill",
"padding": 10,
"bg": "purple/12",
"corner": 10,
"children": [
{"type": "rect", "w": 4, "fill": "purple", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 2,
"children": [
{
"type": "text",
"text": "Design review",
"style": "title3",
"weight": "semibold",
"color": "primary",
"lines": 2
},
{
"type": "text",
"text": "11:30 – 12:30",
"style": "subheadline",
"weight": "medium",
"color": "purple",
"monoDigits": true
},
{
"type": "text",
"text": "With Priya and Sam · Room 4B",
"style": "footnote",
"color": "secondary",
"lines": 1
}
]
},
{"type": "spacer"}
]
},
{
"type": "text",
"text": "LATER",
"style": "caption2",
"weight": "bold",
"color": "tertiary"
},
{
"type": "vstack",
"align": "leading",
"spacing": 6,
"overflow": "drop",
"more": {
"type": "text",
"text": "+{count} more",
"style": "caption",
"color": "secondary"
},
"children": [
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "teal", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "1:1 with Alex",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "14:00",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
},
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "Sprint 42 retro",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "16:30",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
}
]
},
{"type": "spacer"}
]
}
},
{
"at": "2026-08-11T14:00:00Z",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 10,
"padding": 16,
"bg": "white",
"children": [
{
"type": "hstack",
"children": [
{
"type": "vstack",
"align": "leading",
"spacing": -2,
"children": [
{
"type": "text",
"text": "TUESDAY",
"style": "caption2",
"weight": "bold",
"color": "red"
},
{
"type": "text",
"text": "11",
"size": 32,
"weight": "regular",
"color": "primary"
}
]
},
{"type": "spacer"},
{
"type": "text",
"text": "2 to go",
"style": "caption",
"weight": "semibold",
"color": "secondary"
}
]
},
{
"type": "text",
"text": "NOW",
"style": "caption2",
"weight": "bold",
"color": "teal"
},
{
"type": "hstack",
"spacing": 10,
"w": "fill",
"padding": 10,
"bg": "teal/12",
"corner": 10,
"children": [
{"type": "rect", "w": 4, "fill": "teal", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 2,
"children": [
{
"type": "text",
"text": "1:1 with Alex",
"style": "title3",
"weight": "semibold",
"color": "primary",
"lines": 2
},
{
"type": "text",
"text": "14:00 – 14:30",
"style": "subheadline",
"weight": "medium",
"color": "teal",
"monoDigits": true
},
{
"type": "text",
"text": "Career check-in",
"style": "footnote",
"color": "secondary",
"lines": 1
}
]
},
{"type": "spacer"}
]
},
{
"type": "text",
"text": "LATER",
"style": "caption2",
"weight": "bold",
"color": "tertiary"
},
{
"type": "vstack",
"align": "leading",
"spacing": 6,
"overflow": "drop",
"more": {
"type": "text",
"text": "+{count} more",
"style": "caption",
"color": "secondary"
},
"children": [
{
"type": "hstack",
"spacing": 8,
"children": [
{"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
{
"type": "vstack",
"align": "leading",
"spacing": 0,
"children": [
{
"type": "text",
"text": "Sprint 42 retro",
"style": "subheadline",
"weight": "medium",
"color": "primary",
"lines": 1
},
{
"type": "text",
"text": "16:30",
"style": "caption",
"color": "secondary",
"monoDigits": true
}
]
}
]
}
]
},
{"type": "spacer"}
]
}
},
{
"at": "2026-08-11T16:30:00Z",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 10,
"padding": 16,
"bg": "white",
"children": [
{
"type": "hstack",
"children": [
{
"type": "vstack",
"align": "leading",
"spacing": -2,
"children": [
{
"type": "text",
"text": "TUESDAY",
"style": "caption2",
"weight": "bold",
"color": "red"
},
{
"type": "text",
"text": "11",
"size": 32,
"weight": "regular",
"color": "primary"
}
]
},
{"type": "spacer"},
{
"type": "text",
"text": "1 to go",
"style": "caption",
"weight": "semibold",
"color": "secondary"
}
]
},
{
"type": "text",
"text": "NOW",
"style": "caption2",
"weight": "bold",
"color": "orange"
},
{
"type": "hstack",
"spacing": 10,
"w": "fill",
"padding": 10,
"bg": "orange/12",
"corner": 10,
"children": [
{"type": "rect", "w": 4, "fill": "orange", "corner": 2},
{
"type": "vstack",
"align": "leading",
"spacing": 2,
"children": [
{
"type": "text",
"text": "Sprint 42 retro",
"style": "title3",
"weight": "semibold",
"color": "primary",
"lines": 2
},
{
"type": "text",
"text": "16:30 – 17:30",
"style": "subheadline",
"weight": "medium",
"color": "orange",
"monoDigits": true
},
{
"type": "text",
"text": "Whole team · Big room",
"style": "footnote",
"color": "secondary",
"lines": 1
}
]
},
{"type": "spacer"}
]
},
{
"type": "text",
"text": "Nothing else today.",
"style": "subheadline",
"color": "secondary"
},
{"type": "spacer"}
]
}
}
]
} Entry rules
-
The app sorts entries by
at. You do not have to send them in order. - The app drops entries that are less than five minutes apart, because WidgetKit ignores them. Two entries 30 seconds apart become one entry, with no error.
- The app keeps at most 60 entries. It discards the rest.
- The 300-node limit counts all entries together, not each entry. If the views are large, send as many future states as fit. The next fetch brings the rest. The team rota example sends the next few shift changes and asks for a refresh every hour.
-
An entry with no
atstarts immediately. A plainviewis a single entry with no time. -
An entry can have its own
accessibility. It replaces theaccessibilityof the envelope while that entry is on screen. Set it when the entries say different things, because one label cannot be correct for all of them.
Use timers for countdowns
A timer node updates on the phone every second and needs no timeline entry.
If a value depends only on the clock, use a timer. Do not send a number that your server
calculates again for each fetch.
// Refreshing every minute to update a countdown: you will not get the refreshes,
// and the widget will be wrong between the ones you do get.
{ "v": 1, "refresh": 60, "view": { "type": "text", "text": "6 min" } }
// The device counts down on its own. One fetch covers the whole wait.
{ "v": 1, "refresh": 900, "view": { "type": "timer", "until": "2026-08-11T09:06:00Z" } } Choosing an interval
| Kind of data | Interval | Why |
|---|---|---|
| Anything derived from the clock | 3600+ | Use a timer node. The phone counts without a fetch. |
| A schedule you already know | 3600–21600 | Send it as entries. Fetch again only when the schedule can change. |
| Metrics, queues, build status | 900–1800 | You cannot predict this data. Use the refresh budget for it. |
| Anything faster than five minutes | None |
The app clamps the value to 300, and iOS does not fetch that often. A
widget is not a live dashboard.
|
The budget is for each widget instance. A person who adds the same URL in three sizes causes three separate sets of fetches. Make payloads cheap to generate.