docs(runs): add description and example to retrieve endpoint (closes … #2497
Conversation
|
WalkthroughAdds docs for the Retrieve Run endpoint in Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. 📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
Pre-merge checks (2 passed, 1 warning)❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/management/runs/retrieve.mdx (1)
6-6: Clarify response fields and auth prerequisites.Recommend explicitly noting authentication (API key or management client) and enumerating key fields (e.g., id, status, payload, output, attempts, createdAt/completedAt) to set expectations.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/management/runs/retrieve.mdx(1 hunks)
🔇 Additional comments (2)
docs/management/runs/retrieve.mdx (2)
8-26: Import confirmed —runsis a top-level export.
packages/trigger-sdk/src/v3/runs.ts exportsexport const runs = { ... retrieve: retrieveRun }; packages/trigger-sdk/src/v3/shared.ts callsruns.retrieve(...). The exampleimport { runs } from "@trigger.dev/sdk"is correct.
3-3: Verify OpenAPI frontmatter path/param nameConfirm the repo's OpenAPI v3 spec uses the same path parameter name as the frontmatter in docs/management/runs/retrieve.mdx (line 3: openapi: "v3-openapi GET /api/v3/runs/{runId}"); update the doc or the spec so the placeholder names match (e.g., {runId} vs {id}).
docs/management/runs/retrieve.mdx
Outdated
| const result = await runs.retrieve("run_1234"); | ||
|
|
||
| if (result.isSuccess) { | ||
| console.log("Run was successful with output", result.output); | ||
| } |
There was a problem hiding this comment.
Fix example: likely incorrect API shape (no isSuccess on run), add error handling, and avoid duplicate logs.
In the SDK, runs.retrieve typically returns a Run object with a status field (e.g., "SUCCESS" | "FAILED"), not a { isSuccess, output } wrapper. Also, you log output twice and don’t handle 404/network errors. Proposed fix:
-import { runs } from "@trigger.dev/sdk";
-
-const result = await runs.retrieve("run_1234");
-
-if (result.isSuccess) {
- console.log("Run was successful with output", result.output);
-}
-
-console.log("Run status:", result.status);
-console.log("Payload:", result.payload);
-console.log("Output:", result.output);
-
-for (const attempt of result.attempts) {
- if (attempt.status === "FAILED") {
- console.log("Attempt failed with error:", attempt.error);
- }
-}
+import { runs } from "@trigger.dev/sdk";
+
+const runId = "run_1234";
+try {
+ const run = await runs.retrieve(runId);
+
+ if (run.status === "SUCCESS") {
+ console.log("Run was successful with output:", run.output);
+ }
+
+ console.log("Run status:", run.status);
+ console.log("Payload:", run.payload);
+ console.log("Output:", run.output);
+
+ for (const attempt of run.attempts ?? []) {
+ if (attempt.status === "FAILED") {
+ console.log("Attempt failed with error:", attempt.error?.message ?? attempt.error);
+ }
+ }
+} catch (err) {
+ console.error("Failed to retrieve run", runId, err);
+}Also applies to: 17-25
🤖 Prompt for AI Agents
In docs/management/runs/retrieve.mdx around lines 11 to 15 (and similarly lines
17–25), the example assumes runs.retrieve returns { isSuccess, output } and logs
output twice; instead update the snippet to use the Run object's status field
(e.g., status === "SUCCESS"), add proper error handling (wrap the call in
try/catch and handle network/404 errors), and remove duplicate console.log calls
so successful runs log the output once and failed/404 cases log an appropriate
error or status message.
Checklist
I have followed every step in the contributing guide
The PR title follows the convention
I ran and tested that the docs page renders locally
Changelog
docs: add description and example to Runs “Retrieve run” page
Before: page showed no content beyond title
After: page displays description, TS example, and OpenAPI details