> ## Documentation Index
> Fetch the complete documentation index at: https://www.myhamlet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Incremental sync

> Pull only what changed since your last run with updated_since.

To sync efficiently, fetch only the records that changed since your last run rather than
re-paging the entire collection every time.

## `updated_since`

Pass `updated_since` — an ISO-8601 timestamp **with an offset** (a `Z` or numeric offset,
e.g. `2026-05-01T18:22:10Z`). It returns records with `updated_at` at or after that time:

```bash theme={null}
curl "https://api.myhamlet.com/v1/locations?updated_since=2026-05-01T18:22:10Z" \
  -H "Authorization: Bearer hmlt_your_api_key"
```

`updated_since` **composes with the cursor** — page through the filtered results exactly
as on the [Pagination](/pagination) page, just with `updated_since` added to each request.

<Warning>
  A malformed or offset-less `updated_since` (for example `2026-05-01` or
  `2026-05-01T18:22:10` with no `Z`) returns `400` (`invalid_request`).
</Warning>

## A durable sync loop

Because results are ordered by `updated_at` ascending, a robust sync stores the
`updated_at` of the last item it processed and passes it as `updated_since` on the next
run:

```python theme={null}
import requests

base = "https://api.myhamlet.com/v1/locations"
headers = {"Authorization": "Bearer hmlt_your_api_key"}

# high_water_mark is persisted between runs (e.g. in your database)
def sync(high_water_mark):
    cursor = None
    while True:
        params = {"per_page": 100, "updated_since": high_water_mark}
        if cursor:
            params["cursor"] = cursor
        page = requests.get(base, headers=headers, params=params).json()
        for item in page["data"]:
            upsert(item)
            high_water_mark = item["updated_at"]  # advance the watermark
        cursor = page["next_cursor"]
        if cursor is None:
            break
    return high_water_mark  # persist for the next run
```

<Tip>
  `updated_since` is inclusive, so re-running with a stored watermark may re-return the
  last record you already saw. Make your write idempotent (upsert by `uuid`) so replays
  are harmless.
</Tip>