Monatsauswertung 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/monthsScopeevaluations:read

GET /api/v1/evaluations/months liefert für jeden Mitarbeiter und Monat die Summen der Monatsauswertung: Soll, Gutschriften, Arbeitszeit, Korrektur, vertraglich abgegoltene Überstunden, den Monatssaldo (Über- bzw. Minusstunden des Monats) und den Stand des Arbeitszeitkontos einschließlich des Übertrags aus dem Vorjahr. Die Werte stimmen mit der Monatsauswertung in TimeMonkey überein. Benötigter Scope: evaluations:read (Berechtigung Auswertungen).

• Der Zeitraum umfasst höchstens 12 Monate, und to darf nicht in der Zukunft liegen. Der laufende Monat ist erlaubt und zählt bis heute (wie „bis heute“ in der App).
• Enthalten sind nur Monate, in denen der Mitarbeiter ausgewertet wird: ab Vertragsbeginn bis zum Austritt.
• Enthalten sind aktive und inaktive Mitarbeiter.
• Die Einträge sind nach employeeId, dann month sortiert.

Rechenintensive Abfrage

TimeMonkey berechnet die Werte bei jedem Abruf vollständig neu. Für den Stand des Arbeitszeitkontos rechnet es jedes Jahr ab Januar; auch eine Abfrage nur für November rechnet also die Monate davor mit.

• Für einen regelmäßigen Abgleich genügt meist der laufende Monat (from und to gleich), dazu einmalig der Vormonat nach Monatsende.
• 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	Monat YYYY-MM	Erster Monat (inklusive)
to	ja	Monat YYYY-MM	Letzter Monat (inklusive). Höchstens 12 Monate ab from, nicht in der Zukunft
employeeId	nein	ID	Nur Monate 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
month	Monat YYYY-MM	Monat
employeeId	String	ID des Mitarbeiters
through	Datum YYYY-MM-DD	Letzter eingerechneter Tag. Im laufenden Monat ist das heute, sonst der Monatsletzte
contractMs	Zahl	Vertragliche Arbeitszeit des Monats
creditMs	Zahl	Bezahlte Gutschriften für Feiertage, Krankheit, Urlaub und andere bezahlte Abwesenheiten
targetMs	Zahl	Soll = contractMs − creditMs
workedMs	Zahl	Bewertete Arbeitszeit
plannedMs	Zahl	Geplante Arbeitszeit laut Schichtplan
correctionMs	Zahl	Manuelle Korrektur des Monats, positiv oder negativ
compensatedOvertimeMs	Zahl	Vertraglich abgegoltene Überstunden: Summe aus Tagesregel und Monatsregel
balanceMs	Zahl	Monatssaldo = workedMs + correctionMs − targetMs − compensatedOvertimeMs. Positiv sind Überstunden, negativ Minusstunden
accountMs	Zahl	Arbeitszeitkonto am Ende von through: Übertrag aus dem Vorjahr plus die Monatssalden des Jahres bis einschließlich dieses Monats
incomplete	Boolean	true, wenn mindestens ein Tag des Monats unvollständige Stempel hat. Diese Tage zählen noch ohne Arbeitszeit

Beispiel

curl

Terminal

curl -s "https://api.time.monkeymed.de/api/v1/evaluations/months?from=2026-10&to=2026-11&limit=500" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

JavaScript

evaluation-months.mjs

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

for (const month of months.filter((entry) => entry.month === '2026-11')) {
  console.log(`${month.employeeId}: Konto ${(month.accountMs / 3600000).toFixed(2)} h (Stand ${month.through})`);
}

Python

evaluation_months.py

import os

import requests

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

for month in (m for m in months if m["month"] == "2026-11"):
    print(f"{month['employeeId']}: Konto {month['accountMs'] / 3_600_000:.2f} h (Stand {month['through']})")

200 OK

{
  "data": [
    {
      "month": "2026-10",
      "employeeId": "650a1b2c3d4e5f6071829304",
      "through": "2026-10-31",
      "contractMs": 633600000,
      "creditMs": 57600000,
      "targetMs": 576000000,
      "workedMs": 585000000,
      "plannedMs": 576000000,
      "correctionMs": 0,
      "compensatedOvertimeMs": 0,
      "balanceMs": 9000000,
      "accountMs": 45000000,
      "incomplete": false
    },
    {
      "month": "2026-11",
      "employeeId": "650a1b2c3d4e5f6071829304",
      "through": "2026-11-09",
      "contractMs": 172800000,
      "creditMs": 0,
      "targetMs": 172800000,
      "workedMs": 174600000,
      "plannedMs": 172800000,
      "correctionMs": 0,
      "compensatedOvertimeMs": 0,
      "balanceMs": 1800000,
      "accountMs": 46800000,
      "incomplete": false
    }
  ],
  "nextCursor": null
}

Im Beispiel hatte die Mitarbeiterin im Oktober 176 Stunden Vertragszeit und war zwei Tage bezahlt krank (16 Stunden Gutschrift). Ihr Soll lag damit bei 160 Stunden; sie hat 162,5 Stunden gearbeitet, also 2,5 Überstunden. Ihr Arbeitszeitkonto stand Ende Oktober bei 12,5 Stunden und am 9. November, dem Tag des Abrufs, bei 13 Stunden.