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:
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 page, just with updated_since added to each request.
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).
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:
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
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.
