You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Understanding the lifecycle of task execution in Trigger.dev"
4
4
---
5
5
6
-
In Trigger.dev, the concepts of Runs and Attempts are fundamental to understanding how tasks are executed and managed. This article explains these concepts in detail and provides insights into the various states a Run can go through during its lifecycle.
6
+
In Trigger.dev, the concepts of runs and attempts are fundamental to understanding how tasks are executed and managed. This article explains these concepts in detail and provides insights into the various states a run can go through during its lifecycle.
7
7
8
-
## What are Runs?
8
+
## What are runs?
9
9
10
-
A Run is created when you trigger a task (e.g calling `yourTask.trigger({ foo: "bar" })`). It represents a single instance of a task being executed and contains the following key information:
10
+
A run is created when you trigger a task (e.g calling `yourTask.trigger({ foo: "bar" })`). It represents a single instance of a task being executed and contains the following key information:
11
11
12
12
- A unique run ID
13
13
- The current status of the run
14
14
- The payload (input data) for the task
15
15
- Lots of other metadata
16
16
17
-
## The Run Lifecycle
17
+
## The run lifecycle
18
18
19
-
A Run can go through **various** states during its lifecycle. The following diagrams illustrate the possible state transitions:
19
+
A run can go through **various** states during its lifecycle. The following diagram illustrates a typical state transition where a single run is triggered and completes successfully:
20
20
21
21
22
22
23
+
Runs can also find themselves in lots of other states depending on what's happening at any given time. The following sections describe all the possible states in more detail.
24
+
23
25
### Initial States
24
26
25
-
<Iconicon="rectangle-history"iconType="solid"color="#FBBF24"size={17} /> **Waiting for deploy**: If a task is triggered before it has been deployed, the Run enters this state and waits for the task to be deployed.
27
+
<Iconicon="rectangle-history"iconType="solid"color="#FBBF24"size={17} /> **Waiting for deploy**: If a task is triggered before it has been deployed, the run enters this state and waits for the task to be deployed.
26
28
27
-
<Iconicon="clock"iconType="solid"color="#878C99"size={17} /> **Delayed**: When a Run is triggered with a delay, it enters this state until the specified delay period has passed.
29
+
<Iconicon="clock"iconType="solid"color="#878C99"size={17} /> **Delayed**: When a run is triggered with a delay, it enters this state until the specified delay period has passed.
28
30
29
-
<Iconicon="rectangle-history"iconType="solid"color="#878C99"size={17} /> **Queued**: The Run is ready to be executed and is waiting in the queue.
31
+
<Iconicon="rectangle-history"iconType="solid"color="#878C99"size={17} /> **Queued**: The run is ready to be executed and is waiting in the queue.
30
32
31
33
### Execution States
32
34
@@ -40,7 +42,7 @@ A Run can go through **various** states during its lifecycle. The following diag
40
42
41
43
<Iconicon="circle-check"iconType="solid"color="#28BF5C"size={17} /> **Completed**: The task has successfully finished execution.
42
44
43
-
<Iconicon="ban"iconType="solid"color="#878C99"size={17} /> **Canceled**: The Run was manually canceled by the user.
45
+
<Iconicon="ban"iconType="solid"color="#878C99"size={17} /> **Canceled**: The run was manually canceled by the user.
44
46
45
47
<Iconicon="circle-xmark"iconType="solid"color="#E11D48"size={17} /> **Failed**: The task has failed to complete successfully.
46
48
@@ -52,30 +54,30 @@ A Run can go through **various** states during its lifecycle. The following diag
52
54
53
55
<Iconicon="bug"iconType="solid"color="#E11D48"size={17} /> **System failure**: An unrecoverable system error has occurred.
54
56
55
-
<Iconicon="trash-can"iconType="solid"color="#878C99"size={17} /> **Expired**: The Run's Time-to-Live (TTL) has passed before it could start executing.
57
+
<Iconicon="trash-can"iconType="solid"color="#878C99"size={17} /> **Expired**: The run's Time-to-Live (TTL) has passed before it could start executing.
56
58
57
59
## Attempts
58
60
59
-
An Attempt represents a single execution of a task within a Run. A Run can have one or more Attempts, depending on the task's retry settings and whether it fails. Each Attempt has:
61
+
An attempt represents a single execution of a task within a run. A run can have one or more attempts, depending on the task's retry settings and whether it fails. Each attempt has:
60
62
61
63
- A unique attempt ID
62
64
- A status
63
65
- An output (if successful) or an error (if failed)
64
66
65
-
When a task fails, it will be retried according to its retry settings, creating new Attempts until it either succeeds or reaches the retry limit.
67
+
When a task fails, it will be retried according to its retry settings, creating new attempts until it either succeeds or reaches the retry limit.
66
68
67
69
68
70
69
-
## Run Completion
71
+
## Run completion
70
72
71
-
A Run is considered finished when:
73
+
A run is considered finished when:
72
74
73
-
1. The last Attempt succeeds, or
74
-
2. The task has reached its retry limit and all Attempts have failed
75
+
1. The last attempt succeeds, or
76
+
2. The task has reached its retry limit and all attempts have failed
75
77
76
-
At this point, the Run will have either an output (if successful) or an error (if failed).
78
+
At this point, the run will have either an output (if successful) or an error (if failed).
77
79
78
-
## Advanced Run Features
80
+
## Advanced run features
79
81
80
82
### Idempotency Keys
81
83
@@ -85,42 +87,42 @@ When triggering a task, you can provide an idempotency key to ensure the task is
- If a Run with the same idempotency key is already in progress, the new trigger will be ignored.
89
-
- If the Run has already finished, the previous output or error will be returned.
90
+
- If a run with the same idempotency key is already in progress, the new trigger will be ignored.
91
+
- If the run has already finished, the previous output or error will be returned.
90
92
91
-
### Canceling Runs
93
+
### Canceling runs
92
94
93
-
You can cancel an in-progress Run using the API or the dashboard:
95
+
You can cancel an in-progress run using the API or the dashboard:
94
96
95
97
```ts
96
98
runs.cancel(runId);
97
99
```
98
100
99
-
When a Run is canceled:
101
+
When a run is canceled:
100
102
101
103
– The task execution is stopped
102
104
103
-
– The Run is marked as canceled
105
+
– The run is marked as canceled
104
106
105
107
– The task will not be retried
106
108
107
-
– Any in-progress child Runs are also canceled
109
+
– Any in-progress child runs are also canceled
108
110
109
111
### Time-to-live (TTL)
110
112
111
-
You can set a TTL when triggering a Run:
113
+
You can set a TTL when triggering a run:
112
114
113
115
```ts
114
116
yourTask.trigger({ foo: "bar" }, { ttl: "10m" });
115
117
```
116
118
117
-
If the Run hasn't started within the specified TTL, it will automatically expire. This is useful for time-sensitive tasks. Note that dev runs automatically have a 10-minute TTL.
119
+
If the run hasn't started within the specified TTL, it will automatically expire. This is useful for time-sensitive tasks. Note that dev runs automatically have a 10-minute TTL.
118
120
119
121
120
122
121
-
### Delayed Runs
123
+
### Delayed runs
122
124
123
-
You can schedule a Run to start after a specified delay:
125
+
You can schedule a run to start after a specified delay:
@@ -130,19 +132,19 @@ This is useful for tasks that need to be executed at a specific time in the futu
130
132
131
133
132
134
133
-
### Replaying Runs
135
+
### Replaying runs
134
136
135
-
You can create a new Run with the same payload as a previous Run:
137
+
You can create a new run with the same payload as a previous run:
136
138
137
139
```ts
138
140
runs.replay(runId);
139
141
```
140
142
141
-
This is useful for re-running a task with the same input, especially for debugging or recovering from failures. The new Run will use the latest version of the task.
143
+
This is useful for re-running a task with the same input, especially for debugging or recovering from failures. The new run will use the latest version of the task.
142
144
143
145
You can also replay runs from the dashboard using the same or different payload. Learn how to do this [here](/replaying).
144
146
145
-
### Waiting for Runs
147
+
### Waiting for runs
146
148
147
149
#### triggerAndWait()
148
150
@@ -158,7 +160,7 @@ Similar to `triggerAndWait()`, the `batchTriggerAndWait()` function lets you bat
158
160
159
161
### Runs API
160
162
161
-
The Runs API provides methods to interact with and manage Runs:
163
+
The runs API provides methods to interact with and manage runs:
These methods allow you to access detailed information about Runs and their Attempts, including payloads, outputs, parent Runs, and child Runs.
182
+
These methods allow you to access detailed information about runs and their attempts, including payloads, outputs, parent runs, and child runs.
181
183
182
-
### Triggering Runs for Undeployed Tasks
184
+
### Triggering runs for undeployed tasks
183
185
184
-
It's possible to trigger a Run for a task that hasn't been deployed yet. The Run will enter the "Waiting for deploy" state until the task is deployed. Once deployed, the Run will be queued and executed normally.
186
+
It's possible to trigger a run for a task that hasn't been deployed yet. The run will enter the "Waiting for deploy" state until the task is deployed. Once deployed, the run will be queued and executed normally.
185
187
This feature is particularly useful in CI/CD pipelines where you want to trigger tasks before the deployment is complete.
0 commit comments