> ## Documentation Index
> Fetch the complete documentation index at: https://ekso.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DataCycle

> Cycle (sprint, iteration, version, release) — a time-boxed grouping of items.

Cycle (sprint, iteration, version, release) — a time-boxed grouping of items. Cycles attach to a board and accumulate items via `cycleId` on each item. Used for planning views, burn-down reports, and per-sprint filtering.

## Sample JSON

Copy, edit, paste. Server-set fields (`id`, `created`, `tenantId`, …) are omitted from the example — they're populated by the server on response.

```json theme={null}
{
  "name": "Sprint 42",
  "description": "Q2 2026 — login & timeout fixes.",
  "boardId": "board_01HBOARD_FEN",
  "order": 42,
  "startDate": "2026-04-15T00:00:00Z",
  "finishDate": "2026-04-29T23:59:59Z",
  "budgetHours": 80,
  "locked": false,
  "closed": false
}
```

## What Ekso fills in

These fields are managed by the server. You don't pass them on writes — they appear on the response.

* **`items`** — Maintained automatically — each item carrying `cycleId == <this cycle's id>` shows up here.

## Fields

| Field         | Type               | Required     | Notes                                                                                                            |
| ------------- | ------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| `entity`      | string • nullable  | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `name`        | string             | **Required** | Display name of the cycle. Sprint-style names (`Sprint 42`) are common; release-style names (`v2.4.0`) work too. |
| `description` | string             | **Required** | Brief summary of what's in this cycle.                                                                           |
| `boardId`     | string             | Optional     | Id of the parent board. A cycle belongs to exactly one board.                                                    |
| `order`       | integer            | Optional     | Ordering hint for cycle lists. Typically the sprint number.                                                      |
| `parent`      | string             | Optional     | Id of a parent cycle, when cycles nest (rare; some teams use this for release-of-sprints hierarchy).             |
| `startDate`   | string • nullable  | Optional     | Cycle start. Optional — leave null for ad-hoc / unscheduled cycles.                                              |
| `finishDate`  | string • nullable  | Optional     | Cycle end.                                                                                                       |
| `budgetHours` | integer            | Optional     | Total time-budget for items in this cycle. Used by burn-down reports.                                            |
| `locked`      | boolean            | Optional     | When true, items can't be added or removed from this cycle.                                                      |
| `closed`      | boolean            | Optional     | When true, the cycle is past — won't appear in active-sprint pickers.                                            |
| `items`       | array\<string>     | Server-set   | Array of item ids assigned to the cycle. Maintained automatically as items' `cycleId` changes.                   |
| `tenantId`    | string             | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `id`          | string             | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `created`     | string (date-time) | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `createdBy`   | string             | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `updated`     | string (date-time) | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `updatedBy`   | string             | Server-set   | Set by the server. Read-only on writes.                                                                          |
| `deleted`     | boolean            | Server-set   | Set by the server. Read-only on writes.                                                                          |

## Used by

### Request body

* `POST /api/board/{boardId}/cycle`
* `PUT /api/board/{boardId}/cycle/{cycleId}`

### Response body

* `GET /api/board/cycle`
* `GET /api/board/{boardId}/cycle/{cycleId}`
* `GET /api/board/{boardId}/cycle`

### CLI

`ekso cycle` — see the [command branches](/cli/branches) page for available verbs. Body for create / update verbs typically passed via `--data @file.json` matching the [sample JSON](#sample-json) above.