Tagesauswertung abrufen

Beta Die REST-API ist in der Beta. Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern.

GET/api/v1/evaluations/daysScopeevaluations:read

GET /api/v1/evaluations/days liefert für jeden Mitarbeiter und Tag die Zeilen der Monatsauswertung: vertragliche Arbeitszeit, bewertete Arbeitszeit, Gutschriften für Abwesenheiten und Feiertage, vertraglich abgegoltene Überstunden und den Tagessaldo. TimeMonkey rechnet dafür mit genau derselben Logik wie die Auswertung in der App; die Werte stimmen mit der Monatsauswertung überein. Benötigter Scope: evaluations:read (Berechtigung Auswertungen).

Enthalten sind Tage mit vertraglicher Arbeitszeit, Arbeitszeit, Stempeln, einer geplanten Schicht oder einer Abwesenheit. Tage ohne all das (zum Beispiel ein freier Samstag) fehlen.
Enthalten sind aktive und inaktive Mitarbeiter.
Die Einträge sind nach employeeId, dann date sortiert.
Der Zeitraum darf höchstens 92 Tage umfassen, und to darf nicht in der Zukunft liegen. Der heutige Tag ist erlaubt.
Vor Vertragsbeginn, nach dem Austritt und während einer Elternzeit mit pausiertem Arbeitszeitkonto zählen die Tage wie in der App nicht: Alle Stundenwerte sind dann 0.

Monatssaldo und Arbeitszeitkonto liefert die Monatsauswertung, Übertrag und Urlaubskonto die Jahresauswertung.

Rechenintensive Abfrage

TimeMonkey berechnet die Werte bei jedem Abruf vollständig neu. Diese Abfrage ist deshalb deutlich aufwendiger als etwa das Abrufen von Stempeln.

Frage nur die Zeiträume und Mitarbeiter ab, die du brauchst, und speichere die Ergebnisse bei dir.
Eine Seite kann weniger Einträge als limit enthalten, weil die Rechenzeit pro Seite begrenzt ist. Folge immer nextCursor, bis er null ist.
Bitte beachte die Hinweise zur fairen Nutzung.

Parameter

Name	Pflicht	Typ	Beschreibung
`from`	ja	Datum `YYYY-MM-DD`	Erster Tag des Zeitraums (inklusive, Europe/Berlin)
`to`	ja	Datum `YYYY-MM-DD`	Letzter Tag des Zeitraums (inklusive, Europe/Berlin). Höchstens 92 Tage, nicht in der Zukunft
`employeeId`	nein	ID	Nur Tage dieses Mitarbeiters
`limit`	nein	Ganzzahl 1–500	Einträge pro Seite, höchstens. Standard: `100`
`cursor`	nein	String	Wert von `nextCursor` aus der vorherigen Antwort

Antwortfelder

Alle Zeiten sind Dauern in Millisekunden (siehe Dauern).

Feld	Typ	Beschreibung
`date`	Datum `YYYY-MM-DD`	Kalendertag in Europe/Berlin
`employeeId`	String	ID des Mitarbeiters
`contractMs`	Zahl	Vertragliche Arbeitszeit des Tages (Spalte „Vertragliche Arbeitszeit“ der Monatsauswertung)
`workedMs`	Zahl	Bewertete Arbeitszeit (Spalte „Arbeitszeit“) nach Pausen, gesetzlichem Pausenabzug, Start-/Endzeit-Begrenzung und Arbeitszeitpauschale, mindestens `0`. Die Arbeitszeitpauschale (`dailyDeductionMs`) ist bereits enthalten; nicht erneut addieren. An Feiertagen hängt der Wert von der Feiertagseinstellung ab.
`creditMs`	Zahl	Summe der bezahlten Gutschriften des Tages, zum Beispiel für Feiertag, Krankheit oder Urlaub
`compensatedOvertimeMs`	Zahl	Vertraglich abgegoltene Überstunden nach der Tagesregel. Eine Monatsregel wirkt erst auf den ganzen Monat und steht nur in der Monatsauswertung.
`balanceMs`	Zahl	Tagessaldo = `workedMs + creditMs − contractMs − compensatedOvertimeMs`
`dailyDeductionMs`	Zahl	Angewandte Arbeitszeitpauschale, bereits in `workedMs` enthalten; `0` an Tagen ohne Arbeitszeit
`breakMs`	Zahl	Pausen des Tages. Bei automatischem Pausenabzug und geplanten Pausen kann der Wert auch ohne Stempel größer als `0` sein.
`legalBreakMs`	Zahl	Abzug für gesetzliche Pausen. Nur wenn die automatische Berücksichtigung gesetzlicher Pausen in den Einstellungen aktiv ist, sonst `0`
`plannedMs`	Zahl	Geplante Arbeitszeit laut veröffentlichtem Schichtplan (auch verbundener Standorte) nach Arbeitszeitpauschale und gesetzlichem Pausenabzug; `0` ohne geplante Schicht
`start`	Zeitpunkt oder `null`	Beginn der Arbeitszeit (ISO 8601, UTC); `null` ohne Stempel
`end`	Zeitpunkt oder `null`	Ende der Arbeitszeit (ISO 8601, UTC); `null`, solange der Tag unvollständig ist
`incomplete`	Boolean	`true` bei einer ungeraden Anzahl von Stempeln, zum Beispiel wenn das Ausstempeln fehlt. Der Tag enthält dann noch keine bewertete Arbeitszeit
`holiday`	Objekt oder `null`	Feiertag am Standort bzw. eingetragener Feiertag mit `name` (oder `null`); sonst `null`
`absences`	Liste	Abwesenheiten und Gutschriften des Tages (Spalte „Sonstiges“), nur genehmigte. Felder siehe unten
`accountPaused`	Boolean	`true` bei Elternzeit mit pausiertem Arbeitszeitkonto; alle Stundenwerte sind dann `0`

Ein Eintrag in absences:

Feld	Typ	Beschreibung
`type`	String	Art wie bei Abwesenheiten, zum Beispiel `Vacation`, `Sickness` oder `Holiday`
`paid`	Boolean	`true`, wenn der Tag bezahlt ist und deshalb gutgeschrieben wird
`durationMs`	Zahl	Stunden des Eintrags an diesem Tag. Bei bezahlten Einträgen ist das die Gutschrift, die in `creditMs` enthalten ist
`days`	Zahl	`1` oder `0.5` bei einem halben Tag

Abwesenheitsart mit evaluations:read

Wie die Spalte „Sonstiges“ der Monatsauswertung nennt absences die Art der Abwesenheit, also zum Beispiel auch Krankheit. Diese Angabe ist mit dem Scope evaluations:read abrufbar, auch ohne absences:read. Freitext, Notizen, Dateien und Angaben zu Kindern liefert die Tagesauswertung nicht.

Beispiel

curl
JavaScript
Python

Terminal
curl -s "https://api.time.monkeymed.de/api/v1/evaluations/days?from=2026-10-01&to=2026-10-31&employeeId=650a1b2c3d4e5f6071829304&limit=500" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

evaluation-days.mjs
const days = [];
let cursor;
do {
  const query = new URLSearchParams({
    from: '2026-10-01',
    to: '2026-10-31',
    employeeId: '650a1b2c3d4e5f6071829304',
    limit: '500',
    ...(cursor && {cursor}),
  });
  const response = await fetch(`https://api.time.monkeymed.de/api/v1/evaluations/days?${query}`, {
    headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`},
  });
  const page = await response.json();
  days.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);

const balanceHours = days.reduce((sum, day) => sum + day.balanceMs, 0) / 3600000;
const sickDays = days.filter((day) => day.absences.some((absence) => absence.type === 'Sickness'));
console.log(`Saldo ${balanceHours.toFixed(2)} h, Krankheitstage: ${sickDays.map((day) => day.date).join(', ')}`);

evaluation_days.py
import os

import requests

days, cursor = [], None
while True:
    params = {"from": "2026-10-01", "to": "2026-10-31", "employeeId": "650a1b2c3d4e5f6071829304", "limit": 500}
    if cursor:
        params["cursor"] = cursor
    response = requests.get(
        "https://api.time.monkeymed.de/api/v1/evaluations/days",
        headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
        params=params,
        timeout=60,
    )
    response.raise_for_status()
    page = response.json()
    days += page["data"]
    cursor = page["nextCursor"]
    if not cursor:
        break

balance_hours = sum(day["balanceMs"] for day in days) / 3_600_000
sick_days = [day["date"] for day in days if any(a["type"] == "Sickness" for a in day["absences"])]
print(f"Saldo {balance_hours:.2f} h, Krankheitstage: {', '.join(sick_days)}")

200 OK
{
  "data": [
    {
      "date": "2026-10-19",
      "employeeId": "650a1b2c3d4e5f6071829304",
      "contractMs": 28800000,
      "workedMs": 30600000,
      "creditMs": 0,
      "compensatedOvertimeMs": 0,
      "balanceMs": 1800000,
      "dailyDeductionMs": 0,
      "breakMs": 1800000,
      "legalBreakMs": 0,
      "plannedMs": 27000000,
      "start": "2026-10-19T06:00:00.000Z",
      "end": "2026-10-19T15:00:00.000Z",
      "incomplete": false,
      "holiday": null,
      "absences": [],
      "accountPaused": false
    },
    {
      "date": "2026-10-20",
      "employeeId": "650a1b2c3d4e5f6071829304",
      "contractMs": 28800000,
      "workedMs": 0,
      "creditMs": 28800000,
      "compensatedOvertimeMs": 0,
      "balanceMs": 0,
      "dailyDeductionMs": 0,
      "breakMs": 0,
      "legalBreakMs": 0,
      "plannedMs": 27000000,
      "start": null,
      "end": null,
      "incomplete": false,
      "holiday": null,
      "absences": [
        {"type": "Sickness", "paid": true, "durationMs": 28800000, "days": 1}
      ],
      "accountPaused": false
    }
  ],
  "nextCursor": null
}

Im Beispiel hat die Mitarbeiterin am 19. Oktober von 08:00 bis 17:00 Uhr deutscher Zeit (06:00 bis 15:00 UTC) mit 30 Minuten Pause gearbeitet, also 8,5 Stunden bei 8 Stunden Soll: Tagessaldo +30 Minuten. Am 20. Oktober war sie krank; die bezahlte Krankheit wird mit 8 Stunden gutgeschrieben, der Tagessaldo ist 0.

Parameter​

Antwortfelder​

Beispiel​

Parameter

Antwortfelder

Beispiel