> For the complete documentation index, see [llms.txt](https://teamleader-sdk.mcore-services.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://teamleader-sdk.mcore-services.dev/api-reference/general/user-schedules.md).

# User Schedules

Retrieve per-day working schedules for one or more users in Teamleader Focus.

UserSchedules resource.

Wraps the `userSchedules.list` endpoint (added by Teamleader in the 2026-06-19 changelog). Returns the working schedules of one or more users, expanded per day over a date range of at most 7 days.

This is the successor to `users.getWeekSchedule` (still available on the Users resource, but deprecated in favour of this endpoint).

Only available on accounts with the *Weekly working schedule* feature.

```php
Teamleader::userSchedules()
```

|                          |                                                                       |
| ------------------------ | --------------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\General\UserSchedules`         |
| Create / update / delete | — / — / —                                                             |
| Pagination               | `page_size` / `page_number`; the response includes `meta` with totals |

## Endpoints

* `userSchedules.list`

## Filters

Passed as the first argument to `list()`. Any other key throws.

| Filter     | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `from`     | Required. Start of the date range (inclusive), YYYY-MM-DD                                                  |
| `until`    | Required. End of the date range (inclusive), YYYY-MM-DD. On or after "from"; range may span at most 7 days |
| `user_ids` | Required. Array of user UUIDs to return schedules for                                                      |

## Methods

### `forUser()`

```php
forUser(string $userId, string $from, string $until, array $options = []): array
```

Convenience: schedule for a single user over a date range.

* `$userId` — User UUID
* `$from` — Start date (inclusive), YYYY-MM-DD
* `$until` — End date (inclusive), YYYY-MM-DD
* `$options` — Pagination options

### `list()`

```php
list(array $filters = [], array $options = []): array
```

List the per-day working schedules of one or more users.

Posts to `userSchedules.list`. Non-working days are omitted from each user's schedule. Only available with the *Weekly working schedule* feature.

* `$filters` — Required filter keys: - user\_ids (array\<string>, required): user UUIDs - from (string, required): start date, YYYY-MM-DD (inclusive) - until (string, required): end date, YYYY-MM-DD (inclusive, <= 7 days after "from")
* `$options` — Pagination options: page\_size (default 20), page\_number (default 1)

**Throws** `InvalidArgumentException` When required filters are missing or the date range is invalid

### `forUsers()`

```php
forUsers(array $userIds, string $from, string $until, array $options = []): array
```

Convenience: schedules for several users over a date range.

* `$userIds` — Array of user UUIDs
* `$from` — Start date (inclusive), YYYY-MM-DD
* `$until` — End date (inclusive), YYYY-MM-DD
* `$options` — Pagination options

### `info()`

```php
info($id, $includes = null): array
```

info() is not supported — this endpoint only exposes .list.

### `create()`

```php
create(array $data): array
```

create() is not supported.

### `update()`

```php
update($id, array $data): array
```

update() is not supported.

### `delete()`

```php
delete($id, ...$additionalParams): array
```

delete() is not supported.

## Examples

Get per-day schedules for several users over a week:

```php
$schedules = Teamleader::userSchedules()->list([
    'user_ids' => ['user-uuid-1', 'user-uuid-2'],
    'from'     => '2026-06-01',
    'until'    => '2026-06-07',
]);
```

Get the schedule for a single user:

```php
$schedule = Teamleader::userSchedules()->forUser('user-uuid', '2026-06-01', '2026-06-07');
```