0
# Workflow & Cycle Management
1

2
Development cycle and workflow state management for organizing work, tracking progress, and managing development iterations in Linear.
3

4
## Capabilities
5

6
### Cycle Management
7

8
Manage development cycles for time-boxed work organization and sprint planning.
9

10
```typescript { .api }
11
/**
12
 * Get cycles with filtering and pagination
13
 * @param variables - Query parameters including filters and pagination
14
 * @returns Promise resolving to a connection of cycles
15
 */
16
cycles(variables?: CyclesQueryVariables): LinearFetch<CycleConnection>;
17

18
/**
19
 * Get a single cycle by ID
20
 * @param id - The cycle ID
21
 * @returns Promise resolving to the cycle
22
 */
23
cycle(id: string): LinearFetch<Cycle>;
24

25
/**
26
 * Create a new cycle
27
 * @param input - Cycle creation data
28
 * @returns Promise resolving to the creation result
29
 */
30
createCycle(input: CycleCreateInput): LinearFetch<CyclePayload>;
31

32
/**
33
 * Update an existing cycle
34
 * @param id - The cycle ID to update
35
 * @param input - Cycle update data
36
 * @returns Promise resolving to the update result
37
 */
38
updateCycle(id: string, input: CycleUpdateInput): LinearFetch<CyclePayload>;
39

40
/**
41
 * Archive a cycle
42
 * @param id - The cycle ID to archive
43
 * @returns Promise resolving to the archive result
44
 */
45
archiveCycle(id: string): LinearFetch<ArchivePayload>;
46

47
interface CycleCreateInput {
48
  /** Cycle name */
49
  name: string;
50
  /** Cycle description */
51
  description?: string;
52
  /** Team ID this cycle belongs to */
53
  teamId: string;
54
  /** Cycle start date */
55
  startsAt: DateTime;
56
  /** Cycle end date */
57
  endsAt: DateTime;
58
  /** Whether cycle is completed */
59
  completedAt?: DateTime;
60
}
61

62
interface CycleUpdateInput {
63
  /** Update cycle name */
64
  name?: string;
65
  /** Update cycle description */
66
  description?: string;
67
  /** Update start date */
68
  startsAt?: DateTime;
69
  /** Update end date */
70
  endsAt?: DateTime;
71
  /** Update completion date */
72
  completedAt?: DateTime;
73
}
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
import { LinearClient } from "@linear/sdk";
80

81
const client = new LinearClient({ apiKey: "your-api-key" });
82

83
// Get current cycle for a team
84
const currentCycles = await client.cycles({
85
  filter: {
86
    team: { key: { eq: "ENG" } },
87
    isCurrent: { eq: true }
88
  }
89
});
90

91
// Create a new 2-week cycle
92
const newCycle = await client.createCycle({
93
  name: "Sprint 23",
94
  description: "Focus on performance improvements",
95
  teamId: "team-engineering",
96
  startsAt: "2024-01-15T00:00:00Z",
97
  endsAt: "2024-01-29T00:00:00Z"
98
});
99

100
// Complete a cycle
101
const completedCycle = await client.updateCycle("cycle-id", {
102
  completedAt: new Date().toISOString()
103
});
104
```
105

106
### Workflow States
107

108
Manage workflow states that define the status progression of issues.
109

110
```typescript { .api }
111
/**
112
 * Get workflow states with filtering and pagination
113
 * @param variables - Query parameters
114
 * @returns Promise resolving to a connection of workflow states
115
 */
116
workflowStates(variables?: WorkflowStatesQueryVariables): LinearFetch<WorkflowStateConnection>;
117

118
/**
119
 * Get a single workflow state by ID
120
 * @param id - The workflow state ID
121
 * @returns Promise resolving to the workflow state
122
 */
123
workflowState(id: string): LinearFetch<WorkflowState>;
124

125
/**
126
 * Create a new workflow state
127
 * @param input - Workflow state creation data
128
 * @returns Promise resolving to the creation result
129
 */
130
createWorkflowState(input: WorkflowStateCreateInput): LinearFetch<WorkflowStatePayload>;
131

132
/**
133
 * Update a workflow state
134
 * @param id - The workflow state ID to update
135
 * @param input - Workflow state update data
136
 * @returns Promise resolving to the update result
137
 */
138
updateWorkflowState(id: string, input: WorkflowStateUpdateInput): LinearFetch<WorkflowStatePayload>;
139

140
/**
141
 * Archive a workflow state
142
 * @param id - The workflow state ID to archive
143
 * @returns Promise resolving to the archive result
144
 */
145
archiveWorkflowState(id: string): LinearFetch<ArchivePayload>;
146

147
interface WorkflowStateCreateInput {
148
  /** State name */
149
  name: string;
150
  /** State description */
151
  description?: string;
152
  /** State color */
153
  color: string;
154
  /** State type */
155
  type: WorkflowType;
156
  /** Team ID this state belongs to */
157
  teamId: string;
158
  /** Position in the workflow */
159
  position?: number;
160
}
161

162
interface WorkflowStateUpdateInput {
163
  /** Update state name */
164
  name?: string;
165
  /** Update state description */
166
  description?: string;
167
  /** Update state color */
168
  color?: string;
169
  /** Update position */
170
  position?: number;
171
}
172

173
enum WorkflowType {
174
  Backlog = "backlog",
175
  Unstarted = "unstarted",
176
  Started = "started",
177
  Completed = "completed",
178
  Canceled = "canceled"
179
}
180
```
181

182
### Cycle Analytics & Progress
183

184
Track cycle progress and analytics for performance insights.
185

186
```typescript { .api }
187
/**
188
 * Get cycle analytics for progress tracking
189
 * @param cycleId - The cycle ID to analyze
190
 * @returns Promise resolving to cycle analytics
191
 */
192
cycleAnalytics(cycleId: string): LinearFetch<CycleAnalytics>;
193

194
interface CycleAnalytics {
195
  /** Total issues in cycle */
196
  issueCount: number;
197
  /** Completed issues count */
198
  completedIssueCount: number;
199
  /** In progress issues count */
200
  inProgressIssueCount: number;
201
  /** Backlog issues count */
202
  backlogIssueCount: number;
203
  /** Total story points */
204
  totalStoryPoints: number;
205
  /** Completed story points */
206
  completedStoryPoints: number;
207
  /** Cycle completion percentage */
208
  progress: number;
209
}
210
```
211

212
## Core Workflow & Cycle Types
213

214
```typescript { .api }
215
/** Cycle model representing a development cycle */
216
class Cycle extends Request {
217
  /** Unique cycle identifier */
218
  id: string;
219
  /** Cycle name */
220
  name: string;
221
  /** Cycle description */
222
  description?: string;
223
  /** Cycle number */
224
  number: number;
225
  /** Cycle start date */
226
  startsAt: DateTime;
227
  /** Cycle end date */
228
  endsAt: DateTime;
229
  /** Cycle completion date */
230
  completedAt?: DateTime;
231
  /** Whether cycle is current/active */
232
  isCurrent: boolean;
233
  /** Whether cycle is next */
234
  isNext: boolean;
235
  /** Whether cycle is previous */
236
  isPrevious: boolean;
237
  /** Progress percentage (0-1) */
238
  progress: number;
239
  /** Associated team */
240
  team: Team;
241
  /** Issues in this cycle */
242
  issues: IssueConnection;
243
  /** Unfinished issues from previous cycle */
244
  uncompletedIssuesUponClose: IssueConnection;
245
  /** Creation timestamp */
246
  createdAt: DateTime;
247
  /** Last update timestamp */
248
  updatedAt: DateTime;
249
  /** Archive timestamp */
250
  archivedAt?: DateTime;
251
}
252

253
/** Workflow state model */
254
class WorkflowState extends Request {
255
  /** Unique workflow state identifier */
256
  id: string;
257
  /** State name */
258
  name: string;
259
  /** State description */
260
  description?: string;
261
  /** State color hex code */
262
  color: string;
263
  /** State type enum */
264
  type: WorkflowType;
265
  /** Position in workflow */
266
  position: number;
267
  /** Associated team */
268
  team: Team;
269
  /** Issues in this state */
270
  issues: IssueConnection;
271
  /** Creation timestamp */
272
  createdAt: DateTime;
273
  /** Last update timestamp */
274
  updatedAt: DateTime;
275
  /** Archive timestamp */
276
  archivedAt?: DateTime;
277
}
278

279
/** Response payload for cycle mutations */
280
interface CyclePayload {
281
  /** The mutated cycle */
282
  cycle?: Cycle;
283
  /** Whether the mutation was successful */
284
  success: boolean;
285
  /** Last sync ID */
286
  lastSyncId: number;
287
}
288

289
/** Response payload for workflow state mutations */
290
interface WorkflowStatePayload {
291
  /** The mutated workflow state */
292
  workflowState?: WorkflowState;
293
  /** Whether the mutation was successful */
294
  success: boolean;
295
  /** Last sync ID */
296
  lastSyncId: number;
297
}
298

299
/** Paginated connection of cycles */
300
class CycleConnection extends Connection<Cycle> {
301
  /** Cycles in this page */
302
  nodes: Cycle[];
303
  /** Pagination information */
304
  pageInfo: PageInfo;
305
}
306

307
/** Paginated connection of workflow states */
308
class WorkflowStateConnection extends Connection<WorkflowState> {
309
  /** Workflow states in this page */
310
  nodes: WorkflowState[];
311
  /** Pagination information */
312
  pageInfo: PageInfo;
313
}
314
```