---
title: "Follow changes"
method: GET
path: "/api/buckets/{namespace}/{repo}/events"
tags: ["buckets"]
---

# Follow changes

`GET /api/buckets/{namespace}/{repo}/events`

Server-sent events (`Accept: text/event-stream`) of the bucket's file changes, so clients can stop polling `/tree`.

Events:
- `ready`: `{"cursor"}` — replay (if any) is done, live changes follow. `cursor` may be absent if the feed has seen no change yet.
- `changes`: `{"cursor", "changes": [{"path", "op": "add" | "update" | "delete", "size"?, "xetHash"?, "uploadedAt"?, "mtime"?, "mtimeNanos"?}]}` — a batch of changes coalesced over ~200ms. An `update` only carries the fields that changed (an identical re-upload has just `uploadedAt`); `mtime`/`mtimeNanos` are `null` when a re-upload cleared them. `xetHash` is omitted without content read access.
- `reset`: `{"reason": "cursor_too_old"}` — the requested `cursor`/`since` is older than what the server buffers (about 15 minutes); the stream ends and the client must re-list.
- `reconnect`: `{"cursor"}` — sent after 20 minutes or when the server shuts down (deploys), then the stream ends; reconnect with that cursor. Treat any other end of the stream the same way: reconnect with the last cursor you received.

A `: ping` comment is sent every 30s. Resume with `?cursor=` (exclusive) or `?since=` (inclusive); without either, only live changes are sent.

## Path parameters

- `namespace` string, required
- `repo` string, required

## Query parameters

- `cursor` string — Opaque cursor from a previous `ready`/`changes` event; resume after it
- `since` string, date-time — Resume from this instant instead of a cursor (e.g. the bucket's `updatedAt` you last saw)

## Other responses

- `503` — Live follow is not served by this instance, or not caught up yet; retry after `Retry-After` seconds

## Changes

- **2026-09-16** `68387ea03846` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/huggingface/apis/hub-api-endpoints/changes/api/buckets/:namespace/:repo/events/get.md)

---

[API](https://skmtc.dev/huggingface/apis/hub-api-endpoints.md) · [All operations](https://skmtc.dev/huggingface/apis/hub-api-endpoints/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingface/apis/hub-api-endpoints/revisions/61b0b9b74a8a?raw)