# Read the day plan

`GET /v1/tasks/day-plan`

Returns the tasks that the key owner added to the plan for the current day in the Bitrix24 workday widget.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `expand` (query) | string | no | The only value is `tasks`: it adds a `data.tasks` array of task objects to the response. Without the parameter, only identifiers are returned |

The method has no other query parameters: any of them is rejected with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/day-plan?expand=tasks" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/tasks/day-plan?expand=tasks" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/day-plan?expand=tasks', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log(data.taskIds)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/day-plan?expand=tasks', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
console.log(data.taskIds)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | object | The day plan |
| `data.taskIds` | number[] | Identifiers of the day plan tasks in plan order. An empty array if the plan is empty |
| `data.tasks` | object[] | Only with `expand=tasks`. The plan tasks with the same fields as in the [task list](/docs/entities/tasks/list). All fields: [Task fields](/docs/entities/tasks/fields) |

## Response example

A request with `expand=tasks`, two tasks in the plan. The main task fields are shown:

```json
{
  "success": true,
  "data": {
    "taskIds": [4125, 4127],
    "tasks": [
      {
        "id": 4125,
        "title": "Prepare the report",
        "status": 2,
        "responsibleId": 1317,
        "groupId": 155,
        "stageId": 625,
        "deadline": "2026-10-19T18:00:00.000Z"
      },
      {
        "id": 4127,
        "title": "Approve the contract",
        "status": 5,
        "responsibleId": 1317,
        "groupId": 155,
        "stageId": 625,
        "deadline": "2026-10-19T18:00:00.000Z"
      }
    ]
  }
}
```

Without `expand`, only the array of identifiers is returned:

```json
{
  "success": true,
  "data": {
    "taskIds": [4125, 4127]
  }
}
```

## Error response example

400 — an unsupported query parameter or a different `expand` value was passed:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Only expand=tasks is supported"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `expand` is not `tasks`, or another query parameter was passed |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no valid Bitrix24 token |
| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. The reason is in `message` |
| 502 | `BITRIX_ERROR` | Bitrix24 returned a plan with an unexpected structure: `Invalid day plan response` |

Full list of common API errors: [Errors](/docs/errors).

## Known behavior

- **Only your own plan.** The method reads the day plan of the Bitrix24 user the key acts on behalf of. You cannot read another employee's plan. A read-only key works.
- **The API does not fill the plan.** Tasks are added to the plan manually in the Bitrix24 workday widget, with the "Select from list" button in the "Plan for the day" block. Starting a task timer does not add the task to the plan.
- **A completed task stays in the plan.** After completion, its identifier is still returned in `taskIds`.
- **Reading trims the plan to 30 tasks, and the trim is saved.** If the plan has more than 30 tasks, the call returns 30, and the extra tasks are removed from the plan permanently. The removed task is not necessarily the last one added.
- **The day plan and My Plan are different lists.** My Plan stages are set by [moving a task](/docs/tasks/move-stage) and read with the `filter[stagesId]` filter in the [task list](/docs/entities/tasks/list). They do not affect the day plan.

## See also

- [Tasks: kanban, My Plan and the day plan](/docs/tasks)
- [Task kanban stages](/docs/task-stages)
- [Move a task with ordering](/docs/tasks/move-stage)
- [Task list](/docs/entities/tasks/list)
- [Workday](/docs/workday)