Pins and schedules

Every capture is kept for seven days after collection. After that, it is scheduled for deletion unless a pin keeps it. Viewing, querying or reusing a capture does not restart that time. Deletion may finish later.

pin_create and schedule_create are active immediately; there is no draft or activation step. A sql selection runs once at creation and its exact result is locked in. Running the same SQL beforehand with sql_execute is only an estimate. Membership never changes afterwards. Oversized, truncated or empty selections fail instead of creating a partial pin or schedule. Settings → Budgets shows the per-pin and per-schedule limits; a refusal states the limit it hit.

• Pin: days is how long each selected capture is kept from pin creation. captures counts the captures it keeps now (live members) and capture_days is that count × days; expired members are dropped. expires_at is the latest live capture's expiry; once none is live it keeps its last, already past value. pin_update with expected_version moves every live capture's expiry by the change in days, and expires_at with them (shortening lowers it); expired ones are not revived. Extending retention takes effect immediately for captures still kept; captures already near their expiry are verified first. pin_delete removes future protection only. A pin is active until its last capture expires.
• Schedule: every_days is the capture interval since a page's last successful capture, not an expiry. The schedule stays active until paused or deleted. Failures, backoff, domain pacing and capacity can delay a capture.
• pin_days on capture_create or crawl_create creates one pin for that source. Each successful capture joins it and expires pin_days after it was captured. It does not change the capture cadence.
• A schedule always keeps its successful captures in its own pin: pin_days defaults to every_days + 7 (until the next run plus a week) and follows a later every_days change; an explicit pin_days (1–3,650) stays as set. A shorter interval can let kept captures expire; a longer one later does not revive them.
• resolve_bot_challenges on schedule_create asks for paid bot-challenge resolution on every run, only with the user's consent. The organization must allow it at creation; runs after the allowance is withdrawn capture without it.

schedule_urls reports each URL's last_success_at, last_failure_at and next_due_at. next_due_at is an observed calculation, not a reservation. Null does not mean an immediate capture or that the schedule has ended: inspect status_available, pending and the schedule status. schedule_captures lists the captures, successful and failed, in the same row shape as crawl_captures.

A one-day schedule captures daily for as long as it is active. To keep today's evidence without collecting more, pin the captures instead. To fetch a page once, use capture_create, not a schedule.