Get Accounts

GET /accounts

Paginated list of the visible users' account balances.

Authentication: header API_KEY: <userApiKey> (same as all /v2/auth endpoints). No OAuth.

Query parameters

Param	Type	Default	Meaning
userIds	array[string]	– (all visible)	Filter to specific user(s); repeat the param per id (userIds=…&userIds=…). Each id is permission-checked — an unknown id or one you may not see yields 400 (per-item error). If omitted, all visible users are returned.
page	int	1	1-based page
pageSize	int	10	Page size, hard-capped at 10. Smaller values allowed (shorter response time per page); values > 10 are clamped to 10.
timeBalanceAsOf	epoch ms	last end of month	Cut-off day for the time compensation balance
vacationBalanceAsOf	epoch ms	today	Cut-off day for the vacation account — drives both the vacation balance and the vacation entitlement (see callout)
includeInactive	bool	false	false = only users active at the cut-off; true = full history (incl. leavers)

📘

One cut-off drives both vacation balance and entitlement

vacationBalanceAsOf sets a single day at which BOTH the vacation balance (vacationBalanceDays) and the vacation entitlement (vacationEntitlementDays) are evaluated — capped at the leaving date for terminated employees. There is no separate entitlement cut-off param. In the response, vacationBalanceAsOf and vacationEntitlementAsOf are the same day (rendered end-of-day vs start-of-day). The per-employee end of the vacation year can be obtained from GET /users/{userId} (vacationYearStart together with the employment dates).

Request example

REQUEST cURL EXAMPLE

https://mctime.com/api/v2/auth/accounts
//All visible users. Vacation balance AND entitlement as of today; time compensation balance as of the last month-end.

https://mctime.com/api/v2/auth/accounts?userIds=00000000-0000-0000-0000-000000000001&userIds=00000000-0000-0000-0000-000000000002
//Only the given user(s) (repeat userIds per id), if the authenticated user is allowed to see them.

https://mctime.com/api/v2/auth/accounts?vacationBalanceAsOf=1773532800000
//Vacation balance AND entitlement evaluated at the given day (epoch ms), capped at the leaving date for leavers.

https://mctime.com/api/v2/auth/accounts?timeBalanceAsOf=1772323200000
//Time compensation balance evaluated at the given day (epoch ms).

https://mctime.com/api/v2/auth/accounts?includeInactive=true&pageSize=5&page=2
//Full history incl. leavers, 5 users per page, second page.

Response

RESPONSE JSON EXAMPLE

{
  "items": [
    {
      "message": "success",
      "data": {
        "items": [
          {
            "userId": "00000000-0000-0000-0000-000000000001",
            "userFirstName": "John",
            "userLastName": "Doe",
            "timeBalanceHours": 40.0,
            "timeBalanceAsOf": "2026-05-31T23:59:59+00:00",
            "vacationBalanceDays": 7.35,
            "vacationBalanceAsOf": "2026-06-26T23:59:59+00:00",
            "vacationEntitlementDays": 11.5,
            "vacationEntitlementAsOf": "2026-06-26T00:00:00+00:00"
          }
        ],
        "page": 1,
        "pageSize": 10,
        "totalItems": 32,
        "totalCount": 4
      },
      "valid": null
    }
  ],
  "valid": true
}

• data.items[] = the page's users; page, pageSize, totalItems (total users), totalCount (number of pages).
• vacationBalanceAsOf and vacationEntitlementAsOf are the same day (end-of-day vs start-of-day); balance and entitlement are evaluated at that single cut-off, capped at the leaving date for leavers.

Field semantics

Field	Meaning
timeBalanceHours	Time compensation balance in hours at timeBalanceAsOf
vacationBalanceDays	Vacation balance (entitlement − consumption + corrections) at vacationBalanceAsOf
vacationEntitlementDays	(Pro-rated) entitlement at the same cut-off as the balance
timeBalanceAsOf	Day the time compensation balance was evaluated at (default last end of month)
vacationBalanceAsOf	Day the vacation balance was evaluated at (your vacationBalanceAsOf, capped at the leaving date; rendered end-of-day)
vacationEntitlementAsOf	Day the vacation entitlement was evaluated at — the same day as vacationBalanceAsOf (capped at the leaving date; rendered start-of-day)
userId, userFirstName, userLastName	The user's id and name

Status codes

• 401 = exclusively a missing/invalid API_KEY.
• 400 = a not-allowed/not-found userId or bad data.
• Permission: GET requires the VIEW right; only visible users appear.

Rate limit & pagination

• Dedicated bucket 3 req/s (429 on exceed; headers X-Rate-Limit-Remaining / X-Rate-Limit-Retry-After-Seconds).
• Each page triggers up to pageSize full calculations (each over the entire history). For bulk evaluations, use the asynchronous account-balances export in the McTime web app (computed in the background and delivered by e-mail) — this is a web-UI feature, not an API endpoint — instead of enumerating pages via this API.