Keeping a copy in sync

Most integrations keep a local copy of the listings they care about. The API is built for that, and one shape works:

1. Query with sort=updated_asc and an updated_since of your choice.
2. Page through with the cursor, writing each listing to your own store.
3. When you reach the end of the results — or result_window_reached tells you you've reached your plan's paging depth — start a new query with updated_since set to the last updated_at you received.
4. Repeat on whatever schedule suits you. Darak reads its sources twice a day, so more often than hourly buys you little.

curl "https://api.darak.app/v1/listings?city=riyadh&listing_type=rent\
&sort=updated_asc&updated_since=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $DARAK_API_KEY"

Why updated_asc and not newest. Cursors carry an offset into the result set. Under any other sort, a listing added or removed while you're paging shifts rows across a page boundary, so you silently skip some and see others twice. Ordering by updated_at ascending and advancing a watermark means anything you miss on one pass simply arrives on the next.

Expect listings you have already seen. updated_at is the source's own update time where it publishes one, and the last time Darak saw the listing where it doesn't. For those sources it moves every crawl, so those listings re-enter your sync twice a day even when nothing about them changed. Compare before you write, or accept the churn.

Detecting removals. Nothing pushes you a delisting. A listing that is sold, rented, withdrawn or merged as a duplicate simply stops being returned: GET /listings/{id} gives a 404 and GET /listings/batch returns the id in missing_ids. Re-check the ids you hold on a schedule — batch takes them 25 at a time per unit — and treat a miss as removed. Under the terms you have 7 days to stop showing it.

Storage is capped at 30 days. You may keep Darak data to run your application for up to 30 days from when you retrieved it; after that, refresh it or delete it. A sync that keeps its copy current satisfies this by construction, which is the main reason to run one rather than to bulk-load once. Aggregates you derive for internal reporting may be kept longer, as long as they can't be reversed into listing-level data.

Sizing it. Paging depth caps how far one query reaches — 500 results on Free, 5,000 on Starter and Growth, 20,000 on Pro. A city-wide sync will exceed that, which is exactly what the advancing watermark is for. A page of 100 costs 4 units, so a 20,000-listing pass costs 800.