Timesheets

One row per person per calendar day of the window: what was planned, and — when asked for — what happened and how the two differ.

planned alone is the timesheet grid — who was meant to work, when, and what kind of day it was. include=actual adds what was recorded, include=variance adds the difference. Either one is what makes the request expensive, because both require matching the clock-ins.

The four variance numbers are not additive. Arriving three minutes late produces time_late 180 and time_underworked 180 — the same minutes, counted once as lateness and once as unfilled plan. Summing them double-counts.

planned: null means no schedule at all for that day. It is rarer than it sounds: a company created with default settings carries a work and a leave schedule covering four years, so ordinary days off arrive as type: leave rather than as an absent plan. A day that was scheduled and not worked is the other case — a plan, an empty actual, and time_underworked equal to the whole planned time.

There is no per_page. How many rows fifty people produce depends on the window and on who is scheduled, which the caller cannot predict and we can: the page is sized to a row budget instead, and meta.users_per_page reports what that came to. Paging walks people, so one person's whole period always arrives on a single page and a monthly total never has to be assembled across two.

Holidays are not marked: take them from your own calendar. Drafts are never returned.