`client.labeling_time`¶

Bases: SyncResource

Sync labeling-time namespace (client.labeling_time).

heartbeat ¶

heartbeat(project_id: UUID | str, *, asset_id: UUID | str, active_seconds: int, heartbeat_id: UUID | str, class_id: UUID | str | None = None) -> None

Record one active-labeling heartbeat for the calling user (204).

The user is taken from the credential — you can only record your own time. Replays of the same heartbeat_id within 5 min are silent no-ops.

Parameters:

Name	Type	Description	Default
`asset_id`	`UUID \| str`	the project asset being worked on.	required
`active_seconds`	`int`	seconds since the previous heartbeat (1..30).	required
`heartbeat_id`	`UUID \| str`	a fresh client-generated UUID per heartbeat (dedupe key).	required
`class_id`	`UUID \| str \| None`	the project class being labeled, if the time is attributable.	`None`

Raises:

Type	Description
`UnprocessableError`	`active_seconds` outside 1..30 (VALIDATION_ERROR).
`ForbiddenError`	caller is not a project member (AUTH_FORBIDDEN).

report ¶

report(project_id: UUID | str, *, group_by: list[str] | None = None, user_id: UUID | str | None = None, asset_id: UUID | str | None = None, from_: date | str | None = None, to: date | str | None = None, tz: str | None = None) -> LabelingTimeReport

Aggregated active-seconds report (a complete snapshot, not a page).

Parameters:

Name	Type	Description	Default
`group_by`	`list[str] \| None`	dimensions to break rows out by — any non-empty subset of `user` / `class` / `asset` / `day`, in any order. Each becomes a column; rows are summed across the rest. Defaults to `["user"]` server-side when omitted.	`None`
`user_id`	`UUID \| str \| None`	restrict to one user (managers/admins only; labelers are forced to self).	`None`
`asset_id`	`UUID \| str \| None`	restrict to one asset.	`None`
`from_`	`date \| str \| None`	inclusive start day (sent as the `from` query param).	`None`
`to`	`date \| str \| None`	inclusive end day.	`None`
`tz`	`str \| None`	IANA timezone (e.g. `Asia/Seoul`) for the `day` dimension and the `from`/`to` range; defaults to UTC.	`None`

Raises:

Type	Description
`BadRequestError`	unknown `group_by` dimension or unknown `tz` (INVALID_FILTER).
`ForbiddenError`	caller is not a project member (AUTH_FORBIDDEN).

Response models¶

Models returned by client.labeling_time methods (fields, types, and what each means).

Labeling-time report models (the labeling_time resource, ADR-0046).

Heartbeats accumulate active-seconds into per-(user, asset, class, day) buckets; the report aggregates them across whichever dimensions the caller groups by.

LabelingTimeRow ¶

Bases: BaseModel

One aggregated report row. A dimension column is populated only when it was in the group_by list; otherwise it is None (summed across).

LabelingTimeReport ¶