Use APIs and caching

Live data makes an app useful. Caching keeps it fast, reduces unnecessary requests, and gives the upstream service room to breathe. Use the bundled HTTP module to request public data while your app renders:

load("http.star", "http")

def fetch_status():
    response = http.get(
        "https://status.example.com/current.json",
        ttl_seconds = 300,
    )
    if response.status_code != 200:
        return None
    return response.json()

This example reuses a response for five minutes before requesting fresh data.

Pick a useful refresh rate

Set ttl_seconds based on how quickly the source changes and how often users need a new frame. A transit app may need frequent updates; a daily quote does not.

Plan for failure

Prefer this order when an upstream request fails:

Reuse safe cached data.
Show a clear stale or unavailable state.
Log a short diagnostic without user data.
Call fail() only when the app cannot produce a useful frame.

Know what hosted apps can reach

All hosted apps, including owner-private apps, run with network isolation. Private, loopback, link-local, metadata, internal service, and non-approved destinations are blocked. Redirects and DNS results are checked again before a request is allowed.

Before publishing, check that the service permits you to display and cache its data at your expected request volume. Access to an API does not grant rights to its data.

Refresh timing and failures

refresh_interval_seconds in the manifest controls hosted scheduling (30–86,400 seconds, default 300). render.Root(max_age=...) controls how long a frame remains fresh; it does not schedule HTTP requests or override the refresh interval. A max_age of 60 seconds is valid. If refresh happens every 300 seconds, that frame can expire before its replacement arrives. Allow time for scheduling jitter and network delays when choosing freshness. Local preview uses your computer’s network. Hosted rendering needs explicit network_hosts declarations, or network_host_fields setting support. Push a new revision after changing network declarations. Two working public URLs can both fail in Cloud when neither is permitted by the revision. CLI v0.54.10 and later warn when a frame expires before its scheduled refresh. The dashboard shows safe failure details alongside Refresh failed, including last-attempt and success timestamps, retained-frame status and a support reference. It excludes raw app output, credential values and full request URLs.

Start here

Set up

Build apps

Publish

Help

Pick a useful refresh rate

Plan for failure

Know what hosted apps can reach

Refresh timing and failures

​Pick a useful refresh rate

​Plan for failure

​Know what hosted apps can reach

​Refresh timing and failures

Pick a useful refresh rate

Plan for failure

Know what hosted apps can reach

Refresh timing and failures