status

Create a live-updating task progress page the user can watch from any device.

When to use

Call status_create at the start of a long-running task, then status_update or status_log as it progresses. The user gets a URL they can leave open — the page auto-refreshes via SSE.

Example user prompts

  • Give me a live status page while the migration runs.
  • Send me a progress link for the overnight refactor.
  • Let me watch the deploy from my phone.

MCP tool signature

status_create(title: str, project: str | None = None, ttl_hours: int = 24) -> StatusHandle
status_update(status_id, message, percent=None, kv={}) -> None
status_log(status_id, line) -> None
status_finish(status_id, success: bool, summary_md: str) -> None

Example call

handle = status_create(title='Database migration', ttl_hours=6)
print(f'Watch at: {handle["url"]}')

# ...during the migration...
status_update(handle['status_id'], 'Running migrations...', percent=30,
              kv={'tables_done': 4, 'total': 14})
status_log(handle['status_id'], 'ALTER TABLE orders ADD COLUMN v2 ...')

# When done
status_finish(handle['status_id'], success=True,
              summary_md='14 tables migrated. 0 errors.')

Return value

Returns a StatusHandle with status_id and url. The page shows a vertical stream of timestamped log lines, a progress bar when percent is provided, and any key-value pairs. SSE keeps it live.

Credit cost

1 action to create. Updates batch: 1 action covers up to 100 update events per hour on the same resource.

Notes

status is for watching live. For after-the-fact run history, use trace instead.

Recipes

See all recipes for copy-paste patterns that use status and other tools together.