---
title: "Hours of a month"
method: GET
path: "/hours"
tags: ["attendance"]
---

# Hours of a month

`GET /hours`

## Request

- Base URL: `https://api.taktovka.com/v1`
- URL: `https://api.taktovka.com/v1/hours`
- Auth: HTTP bearer

Per person: planned minutes from the published roster, counted minutes from attendance, the working-time fund of an employment contract and the person's own confirmation of the month. The part of the fund that depends on absences is filled only for a key that also has absences:read. `next_cursor` is always null. Counts as 5 requests against the rate limit. Runs one at a time per company; a second call while one is running answers 429 with retry_after.

## Query parameters

- `month` string, required
- `employee` string, uuid
- `location` string, uuid

## Response `200`

OK

- object
  - `data` Hours[], required
    - `employee_id` string, uuid, required
    - `month` string, required: Calendar month, YYYY-MM, years 2000–2100
    - `planned_minutes` integer, required: Elapsed minutes of the published shifts starting in the month
    - `paid_planned_minutes` integer, required: The same less the breaks
    - `counted_minutes` integer, nullable, required: Counted time from the door scan and manual entries, matched to the roster the way the app counts it (rounding, the plan, the break the law requires, a minor's break); null when attendance is off at every place of the person and nothing was clocked
    - `fund` object, nullable, required: Only for an employment contract (SK TPP, CZ HPP) with agreed weekly hours
      - `weekly_hours` number, required
      - `fund_minutes` integer, required: Weekdays of the month that are not a day-off holiday, times a fifth of the weekly hours
      - `holiday_minutes` integer, required: Day-off holidays on weekdays of the month
      - `absence_minutes` integer, nullable, required: Weekdays covered by an approved absence; only with absences:read, null without it
      - `target_minutes` integer, nullable, required: The fund less approved absences: what the plan should reach; only with absences:read, null without it
    - `confirmed` object, nullable, required: The person confirmed the month in the app
      - `confirmed_at` string, date-time, required: ISO 8601 instant
      - `counted_minutes` integer, required: Counted minutes at the moment of the signature
      - `stale` boolean, required: The month was corrected or counts differently since the signature
    - `meals` object, nullable, required: Meals of the month for the payroll accountant, who applies the amounts; null when the company has set no meal policy in the app or the person's contract is outside it
      - `count` integer, required: Shifts that give a meal under the company's policy: more than 4 h of work in Slovakia, at least 3 h in Czechia, the break not counted
      - `second` integer, required: Second meals, on shifts longer than 11 h including the break, when the policy gives them
      - `absence_days` integer, nullable, required: Working days of approved absences that give a meal when the policy includes absences; only with absences:read and without `location`, null otherwise
      - `source` 'attendance' | 'plan' | 'both', nullable, required: Where the shifts were read: counted time where the person clocked in that day at that place, the published plan elsewhere; null without a meal from work
      - `form` 'kitchen' | 'voucher' | 'allowance' | 'choice', required: How the company gives meals at the end of the month
      - `choice` 'voucher' | 'allowance', nullable, required: With form `choice` (Slovakia): what the person picked, null until they pick
  - `next_cursor` string, nullable, required

## Other responses

- `400`: validation_failed, range_too_long or key_in_query
- `401`: unauthenticated, invalid_key, key_revoked or key_expired
- `403`: insufficient_scope (with required_scope)
- `429`: rate_limited (with retry_after and a Retry-After header)

---

[API](https://skmtc.dev/taktovka/apis/taktovka-api.md) · [All operations](https://skmtc.dev/taktovka/apis/taktovka-api/llms.txt) · [OpenAPI document](https://skmtc.dev/taktovka/apis/taktovka-api/revisions/612199b365e1?raw)