Skip to content

Commit 6fb0736

Browse files
ericallamericallam
committed
Add realtime API docs
1 parent 9203bd8 commit 6fb0736

File tree

4 files changed

+209
-1
lines changed

4 files changed

+209
-1
lines changed

‎docs/mint.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,9 @@
212212
{
213213
"group": "Realtime API",
214214
"pages": [
215-
"realtime/overview"
215+
"realtime/overview",
216+
"realtime/subscribe-to-run",
217+
"realtime/subscribe-to-runs-with-tag"
216218
]
217219
},
218220
{

‎docs/realtime/subscribe-to-run.mdx

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: runs.subscribeToRun
3+
sidebarTitle: subscribeToRun
4+
description: Subscribes to all changes to a run.
5+
---
6+
7+
import RunObject from "/snippets/realtime/run-object.mdx";
8+
9+
<RequestExample>
10+
11+
```ts Example
12+
import { runs } from "@trigger.dev/sdk/v3";
13+
14+
for await (const run of runs.subscribeToRun("run_1234")) {
15+
console.log(run);
16+
}
17+
```
18+
19+
</RequestExample>
20+
21+
This function subscribes to all changes to a run. It returns an async iterator that yields the run object whenever the run is updated. The iterator will complete when the run is finished.
22+
23+
### Authentication
24+
25+
This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with one of the following scopes:
26+
27+
- `read:runs`
28+
- `read:runs:<runId>`
29+
30+
To generate a public access token, use the `auth.createPublicToken` function:
31+
32+
```ts
33+
import { auth } from "@trigger.dev/sdk/v3";
34+
35+
// Somewhere in your backend code
36+
const publicToken = await auth.createPublicToken({
37+
scopes: {
38+
read: {
39+
runs: ["run_1234"],
40+
},
41+
},
42+
});
43+
```
44+
45+
### Response
46+
47+
The AsyncIterator yields an object with the following properties:
48+
49+
<RunObject />

‎docs/realtime/subscribe-to-runs-with-tag.mdx

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: runs.subscribeToRunsWithTag
3+
sidebarTitle: subscribeToRunsWithTag
4+
description: Subscribes to all changes to runs with a specific tag.
5+
---
6+
7+
import RunObject from "/snippets/realtime/run-object.mdx";
8+
9+
<RequestExample>
10+
11+
```ts Example
12+
import { runs } from "@trigger.dev/sdk/v3";
13+
14+
for await (const run of runs.subscribeToRunsWithTag("user:1234")) {
15+
console.log(run);
16+
}
17+
```
18+
19+
</RequestExample>
20+
21+
This function subscribes to all changes to runs with a specific tag. It returns an async iterator that yields the run object whenever a run with the specified tag is updated. This iterator will never complete, so you must manually break out of the loop when you no longer want to receive updates.
22+
23+
### Authentication
24+
25+
This function supports both server-side and client-side authentication. For server-side authentication, use your API key. For client-side authentication, you must generate a public access token with one of the following scopes:
26+
27+
- `read:runs`
28+
- `read:tags:<tagName>`
29+
30+
To generate a public access token, use the `auth.createPublicToken` function:
31+
32+
```ts
33+
import { auth } from "@trigger.dev/sdk/v3";
34+
35+
// Somewhere in your backend code
36+
const publicToken = await auth.createPublicToken({
37+
scopes: {
38+
read: {
39+
tags: ["user:1234"],
40+
},
41+
},
42+
});
43+
```
44+
45+
### Response
46+
47+
The AsyncIterator yields an object with the following properties:
48+
49+
<RunObject />

‎docs/snippets/realtime/run-object.mdx

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<ParamField path="id" type="string" required>
2+
The run ID.
3+
</ParamField>
4+
5+
<ParamField path="taskIdentifier" type="string" required>
6+
The task identifier.
7+
</ParamField>
8+
9+
<ParamField path="payload" type="object" required>
10+
The input payload for the run.
11+
</ParamField>
12+
13+
<ParamField path="output" type="object">
14+
The output result of the run.
15+
</ParamField>
16+
17+
<ParamField path="createdAt" type="Date" required>
18+
Timestamp when the run was created.
19+
</ParamField>
20+
21+
<ParamField path="updatedAt" type="Date" required>
22+
Timestamp when the run was last updated.
23+
</ParamField>
24+
25+
<ParamField path="number" type="number" required>
26+
Sequential number assigned to the run.
27+
</ParamField>
28+
29+
<ParamField path="status" type="RunStatus" required>
30+
Current status of the run.
31+
32+
<Accordion title="RunStatus enum">
33+
34+
| Status | Description |
35+
| -------------------- | --------------------------------------------------------------------------------------------------------- |
36+
| `WAITING_FOR_DEPLOY` | Task hasn't been deployed yet but is waiting to be executed |
37+
| `QUEUED` | Run is waiting to be executed by a worker |
38+
| `EXECUTING` | Run is currently being executed by a worker |
39+
| `REATTEMPTING` | Run has failed and is waiting to be retried |
40+
| `FROZEN` | Run has been paused by the system, and will be resumed by the system |
41+
| `COMPLETED` | Run has been completed successfully |
42+
| `CANCELED` | Run has been canceled by the user |
43+
| `FAILED` | Run has been completed with errors |
44+
| `CRASHED` | Run has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage |
45+
| `INTERRUPTED` | Run was interrupted during execution, mostly this happens in development environments |
46+
| `SYSTEM_FAILURE` | Run has failed to complete, due to an error in the system |
47+
| `DELAYED` | Run has been scheduled to run at a specific time |
48+
| `EXPIRED` | Run has expired and won't be executed |
49+
| `TIMED_OUT` | Run has reached it's maxDuration and has been stopped |
50+
51+
</Accordion>
52+
</ParamField>
53+
54+
<ParamField path="durationMs" type="number" required>
55+
Duration of the run in milliseconds.
56+
</ParamField>
57+
58+
<ParamField path="costInCents" type="number" required>
59+
Total cost of the run in cents.
60+
</ParamField>
61+
62+
<ParamField path="baseCostInCents" type="number" required>
63+
Base cost of the run in cents before any additional charges.
64+
</ParamField>
65+
66+
<ParamField path="tags" type="string[]" required>
67+
Array of tags associated with the run.
68+
</ParamField>
69+
70+
<ParamField path="idempotencyKey" type="string">
71+
Key used to ensure idempotent execution.
72+
</ParamField>
73+
74+
<ParamField path="expiredAt" type="Date">
75+
Timestamp when the run expired.
76+
</ParamField>
77+
78+
<ParamField path="ttl" type="string">
79+
Time-to-live duration for the run.
80+
</ParamField>
81+
82+
<ParamField path="finishedAt" type="Date">
83+
Timestamp when the run finished.
84+
</ParamField>
85+
86+
<ParamField path="startedAt" type="Date">
87+
Timestamp when the run started.
88+
</ParamField>
89+
90+
<ParamField path="delayedUntil" type="Date">
91+
Timestamp until which the run is delayed.
92+
</ParamField>
93+
94+
<ParamField path="queuedAt" type="Date">
95+
Timestamp when the run was queued.
96+
</ParamField>
97+
98+
<ParamField path="metadata" type="Record<string, DeserializedJson>">
99+
Additional metadata associated with the run.
100+
</ParamField>
101+
102+
<ParamField path="error" type="SerializedError">
103+
Error information if the run failed.
104+
</ParamField>
105+
106+
<ParamField path="isTest" type="boolean" required>
107+
Indicates whether this is a test run.
108+
</ParamField>

0 commit comments

Comments
 (0)