1# Workflow APIs
2 
3## Step APIs
4 
5```typescript
6// step.do()
7const result = await step.do('step name', async () => { /* logic */ });
8const result = await step.do('step name', { retries, timeout }, async () => {});
9 
10// step.sleep()
11await step.sleep('description', '1 hour');
12await step.sleep('description', 5000); // ms
13 
14// step.sleepUntil()
15await step.sleepUntil('description', Date.parse('2024-12-31'));
16 
17// step.waitForEvent()
18const data = await step.waitForEvent<PayloadType>('wait', {type: 'webhook-type', timeout: '24h'});
19try { const event = await step.waitForEvent('wait', { type: 'approval', timeout: '1h' }); } catch (e) { /* Timeout */ }
20```
21 
22## WorkflowStepContext
23 
24The `WorkflowStepContext` is passed as the first argument to the `step.do()` callback. It provides runtime information about the current step execution.
25 
26```typescript
27type WorkflowStepContext = {
28  step: {
29    name: string;   // Step name as passed to step.do()
30    count: number;  // How many times step.do() called with this name in current run (1-indexed)
31  };
32  attempt: number;  // Current attempt number (1-indexed): 1 = first try, 2 = first retry, etc.
33  config: WorkflowStepConfig; // Resolved config for this step, including runtime defaults
34};
35```
36 
37**Use cases:**
38```typescript
39// Adjust behavior based on retry attempt
40await step.do('call api', { retries: { limit: 3, delay: '5 seconds', backoff: 'exponential' } }, async (ctx) => {
41  if (ctx.attempt > 1) console.log(`Retry attempt ${ctx.attempt} for step "${ctx.step.name}"`);
42  const res = await fetch('https://api.example.com/data');
43  if (!res.ok) throw new Error(`API failed (attempt ${ctx.attempt})`);
44  return res.json();
45});
46 
47```
48 
49## Instance Management
50 
51```typescript
52// Create single
53const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); // id optional, auto-generated if omitted; throws if ID already exists within retention period
54 
55// Create with custom retention (check docs for default per plan)
56const instance = await env.MY_WORKFLOW.create({
57  id: crypto.randomUUID(),
58  params: { userId: 'user123' },
59  retention: '30 days'  // Override default retention period
60});
61 
62// Batch (max 100, idempotent: skips existing IDs)
63const instances = await env.MY_WORKFLOW.createBatch([{id: 'user1', params: {name: 'John'}}, {id: 'user2', params: {name: 'Jane'}}]);
64 
65// Get & Status
66const instance = await env.MY_WORKFLOW.get('instance-id');
67const status = await instance.status(); // {status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'waitingForPause' | 'unknown', error?, output?}
68 
69// Control
70await instance.pause(); await instance.resume(); await instance.terminate(); await instance.restart();
71 
72// Send Events
73await instance.sendEvent({type: 'approval', payload: { approved: true }}); // Must match waitForEvent type
74```
75 
76## Triggering Workflows
77 
78```typescript
79// From Worker
80export default { async fetch(req, env) { const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); return Response.json({ id: instance.id }); }};
81 
82// From Queue
83export default { async queue(batch, env) { for (const msg of batch.messages) { await env.MY_WORKFLOW.create({id: `job-${msg.id}`, params: msg.body}); } }};
84 
85// From Cron
86export default { async scheduled(event, env) { await env.CLEANUP_WORKFLOW.create({id: `cleanup-${Date.now()}`, params: { timestamp: event.scheduledTime }}); }};
87 
88// From Another Workflow (non-blocking)
89export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> {
90  async run(event, step) {
91    const child = await step.do('start child', async () => await this.env.CHILD_WORKFLOW.create({id: `child-${event.instanceId}`, params: {}}));
92  }
93}
94```
95 
96## Error Handling
97 
98```typescript
99import { NonRetryableError } from 'cloudflare:workflows';
100 
101// NonRetryableError
102await step.do('validate', async () => {
103  if (!event.payload.paymentMethod) throw new NonRetryableError('Payment method required');
104  const res = await fetch('https://api.example.com/charge', { method: 'POST' });
105  if (res.status === 401) throw new NonRetryableError('Invalid credentials'); // Don't retry
106  if (!res.ok) throw new Error('Retryable failure'); // Will retry
107  return res.json();
108});
109 
110// Catching Errors
111try { await step.do('risky op', async () => { throw new NonRetryableError('Failed'); }); } catch (e) { await step.do('cleanup', async () => {}); }
112 
113// Idempotency
114await step.do('charge', async () => {
115  const sub = await fetch(`https://api/subscriptions/${id}`).then(r => r.json());
116  if (sub.charged) return sub; // Already done
117  return await fetch(`https://api/subscriptions/${id}`, {method: 'POST', body: JSON.stringify({ amount: 10.0 })}).then(r => r.json());
118});
119```
120 
121## Type Constraints
122 
123Params and step returns must be `Rpc.Serializable<T>`:
124 
125```typescript
126// ✅ Valid types
127type ValidParams = {
128  userId: string;
129  count: number;
130  tags: string[];
131  metadata: Record<string, unknown>;
132};
133 
134// ❌ Invalid types
135type InvalidParams = {
136  callback: () => void;      // Functions not serializable
137  symbol: symbol;            // Symbols not serializable
138  circular: any;             // Circular references not allowed
139};
140 
141// Step returns follow same rules
142const result = await step.do('fetch', async () => {
143  return { userId: '123', data: [1, 2, 3] }; // ✅ Plain object
144});
145 
146// ✅ ReadableStream<Uint8Array> for large binary output (bypasses non-stream step result size limit)
147const stream = await step.do('read from R2', async () => {
148  const obj = await this.env.BUCKET.get('large-file.csv');
149  return obj.body; // Return the ReadableStream directly
150});
151```
152 
153## Sleep & Scheduling
154 
155```typescript
156// Relative
157await step.sleep('wait 1 hour', '1 hour');
158await step.sleep('wait 30 days', '30 days');
159await step.sleep('wait 5s', 5000); // ms
160 
161// Absolute
162await step.sleepUntil('launch date', Date.parse('24 Oct 2024 13:00:00 UTC'));
163await step.sleepUntil('deadline', new Date('2024-12-31T23:59:59Z'));
164```
165 
166Units: second, minute, hour, day, week, month, year.
167Sleeping instances don't count toward concurrency.
168 
169## Parameters
170 
171**Pass from Worker:**
172```typescript
173const instance = await env.MY_WORKFLOW.create({
174  id: crypto.randomUUID(),
175  params: { userId: 'user123', email: '[email protected]' }
176});
177```
178 
179**Access in Workflow:**
180```typescript
181async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
182  const userId = event.payload.userId;
183  const instanceId = event.instanceId;
184  const createdAt = event.timestamp;
185}
186```
187 
188**CLI Trigger:**
189```bash
190npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
191```
192 
193## Wrangler CLI
194 
195```bash
196npm create cloudflare@latest my-workflow -- --template "cloudflare/workflows-starter"
197npx wrangler deploy
198npx wrangler workflows list
199npx wrangler workflows trigger my-workflow '{"userId":"user123"}'
200npx wrangler workflows instances list my-workflow
201npx wrangler workflows instances describe my-workflow instance-id
202npx wrangler workflows instances pause/resume/terminate my-workflow instance-id
203```
204 
205## REST API
206 
207```bash
208# Create
209curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances" -H "Authorization: Bearer {token}" -d '{"id":"custom-id","params":{"userId":"user123"}}'
210 
211# Status
212curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status" -H "Authorization: Bearer {token}"
213 
214# Send Event
215curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events" -H "Authorization: Bearer {token}" -d '{"type":"approval","payload":{"approved":true}}'
216```
217 
218See: [configuration.md](./configuration.md), [patterns.md](./patterns.md)
219