> For the complete documentation index, see [llms.txt](https://docs.samesystem.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samesystem.dev/business-guides/scheduling/planned-schedule.md).

# Planned schedule

{% hint style="info" %}
Only available in API v1.
{% endhint %}

Planned schedule is the published state of the schedule, hence a snapshot of how it looked at that exact moment in time when the schedule was published to the employees.

The is the same endpoint as Actual Schedule, but with the query parameter `?planned=true`.

{% hint style="warning" %}
**Important:** Planned schedule should not be interpreted as the current state of the schedule. It represents only the published version of the schedule at a very specific point in time.

This means that any later changes to start time, end time, change of zone etc. will not be shown when you select ?planned=true as the parameter to the endpoint.
{% endhint %}

Data retrieved from the actual schedule contains all events from the schedule:

* Working hours.
* Absence hours.
* Bonus types.
* Tasks

{% hint style="danger" %}
This endpoint performs time-consuming calculations. 

Response time depends on the number of shops and employees included. 

To improve performance, consider splitting requests into smaller date ranges or limiting the number of shops.
{% endhint %}

### 93-day maximum date-range limit

We have a 93-day maximum date-range limit. If you try to fetch data for more than 93 days, you will receive an error.

### Tasks

The hours are calculated and saved when the shift is saved.

Example of calcuation of hours:

{% code overflow="wrap" %}

```
Shift   : 09:00–17:00
Task    : 12:00–18:00
Break   : 13:00–13:30

Part of the task during the shift    :12:00–17:00 = 5.0 h
Break inside the task                :13:00–13:30 = 0.5 h
Calculation of hours                 :5.0 h − 0.5 h = 4.5 h
```

{% endcode %}

{% hint style="info" %}
The task hours for a shift don't always add up to the shift's hours. Time not assigned to any task is not counted in any task. If two tasks overlap, the shared time counts for both.
{% endhint %}

In the example below, the shift object will return one task

<figure><img src="https://2670147116-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRlKDeTWSTdLA0zl6vlB2%2Fuploads%2FcpiVjzsAI2wz7qJt6HJJ%2Fimage.png?alt=media&amp;token=d9fb626a-4e77-43a3-bf6d-d5363fd2db5c" alt=""><figcaption></figcaption></figure>

```json
"tasks": [
            {
                "id": 2528680979,
                "task_type_id": 5897,
                "name": "Counting the cash register",
                "start_time": 10.0,
                "end_time": 14.75,
                "hours": 4.75,
                "productivity_percent": 80
            }
        ]
```

### Open-shifts

{% hint style="info" %}
**Note:**&#x20;

The **Statistics → Hours/Salary** report in SameSystem includes **open shifts**, while this API endpoint does **not** include open shifts. As a result, customers comparing data returned by the API with the Hours/Salary report may see differences in the totals.
{% endhint %}

### API best practice

For endpoints that perform heavier calculations, integrations should be designed to handle longer response times.

Where possible, reduce the amount of data processed in each request by using **smaller date ranges** or fewer departments. Avoid parallel or aggressive retry requests, as these may increase the load and further extend processing time.

Do not automatically retry requests that fail due to validation or authorization errors (`4xx`), unless the response specifically indicates that a retry is appropriate.

### Latest updates

{% updates format="full" %}
{% update date="2026-10-09" %}

## Tasks

Added support to fetch information about tasks registered in each shifts. In order to fetch tasks, you can include `?tasks=true` and the response will include an array of `scheduleTask` objects under `tasks`.
{% endupdate %}

{% update date="2026-08-10" %}

## Lent out department object

Added support for identifying users temporarily assigned (lent out) to another department. When using `?include_lent_outs=true`, the response now includes a `lent_out_department` object showing the department the user is assigned to for the shift, while the existing `department` object continues to represent the user's normal department.
{% endupdate %}
{% endupdates %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.samesystem.dev/business-guides/scheduling/planned-schedule.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.