# timeclock_list

Get Time Clocks

## Beschreibung

Reads TimeClock entries (check-in / check-out records). One row
per work/pause session, or a full sick/vacation day.

Admin / employer see every member's entries (and may filter by
`user_id`); regular members see only their own and can't pass a
foreign `user_id`.

- `checkin_out` is the real field name (not `checkout_at`).
- `duration_seconds` is null on open entries (`is_open: true`)
  so sums stay safely additive without filtering.
- `created_on` is a local-time date — may differ from
  `checkin_at.to_date` for late-night sessions.
- Full-day sick/vacation still use 00:00–23:59 pair, `category: "work"`.
- `comment == "auto closed"` flags nightly auto-close sweeps.
- Sorted `checkin_at DESC`, capped at 500 rows.

## Zugriff

Zugriffsprofil: `gated`. Module: `timeclock`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja | Account prefix ID (e.g., acct_abc123). |
| `user_id` | string | Nein | User prefix ID (user_…) or @handle / handle (e.g., 'sam' or '@sam'). Admin/employer only for foreign users. |
| `start_date` | string | Nein | Inclusive lower bound on created_on (YYYY-MM-DD). Use alone for a single day. |
| `end_date` | string | Nein | Inclusive upper bound on created_on. Defaults to start_date when only start_date is given — pair them for a range. |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123)."
    },
    "user_id": {
      "type": "string",
      "description": "User prefix ID (user_…) or @handle / handle (e.g., 'sam' or '@sam'). Admin/employer only for foreign users."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Inclusive lower bound on created_on (YYYY-MM-DD). Use alone for a single day."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Inclusive upper bound on created_on. Defaults to start_date when only start_date is given — pair them for a range."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "time_clocks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "TimeClock prefix ID (clk_…)."
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "handle": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              }
            }
          },
          "created_on": {
            "type": "string",
            "format": "date",
            "description": "Calendar day the entry belongs to (local-time assigned at check-in; may differ from checkin_at.to_date for late-night sessions)."
          },
          "checkin_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "checkin_out": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Null when entry is still open. Field name is intentional — not a typo for checkout_at."
          },
          "is_open": {
            "type": "boolean",
            "description": "True iff checkin_out is null."
          },
          "category": {
            "type": "string",
            "enum": [
              "work",
              "pause"
            ]
          },
          "work_location_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "remote",
              "on_site"
            ]
          },
          "sick_day": {
            "type": "boolean"
          },
          "vacation_day": {
            "type": "boolean"
          },
          "comment": {
            "type": [
              "string",
              "null"
            ],
            "description": "AUTO_CHECKOUT_COMMENT='auto closed' marks entries closed by the nightly sweep."
          },
          "duration_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null on open entries to keep sums safely additive."
          }
        },
        "required": [
          "id",
          "user",
          "created_on",
          "is_open",
          "category",
          "sick_day",
          "vacation_day"
        ]
      }
    }
  },
  "required": [
    "time_clocks"
  ],
  "type": "object"
}
```