docs: document undocumented run API endpoints #3120
Conversation
|
WalkthroughThis pull request adds three new Runs API reference pages and corresponding OpenAPI definitions: POST /api/v1/runs/{runId}/tags, GET /api/v1/runs/{runId}/trace, and GET /api/v1/runs/{runId}/events. It introduces three new MDX docs, updates docs/docs.json navigation, and extends docs/v3-openapi.yaml with the three paths, request/response schemas (including new RunTag, RunTags, and SpanDetailedSummary schemas), updated tag constraints, and related code samples. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/v3-openapi.yaml (1)
506-606: Document or cap the size of the events array.
eventsis unbounded in the schema; if the API enforces a limit or pagination, reflect it (e.g.,maxItemsor paging fields) to avoid oversized responses and validator warnings. If the endpoint is intentionally unbounded, consider documenting that explicitly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/v3-openapi.yaml` around lines 506 - 606, The events array in the response schema for operationId get_run_events_v1 (path "/api/v1/runs/{runId}/events") is currently unbounded; update the OpenAPI response to reflect the API behavior by either adding a maxItems (e.g., maxItems: <limit>) and a note in the description or converting the response to a paginated shape (e.g., { events: [...], nextCursor: string, limit: number }) and update the description to document paging semantics; ensure the change is applied to the response schema for the "200" response under that path so validators and consumers know the size/cap behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/v3-openapi.yaml`:
- Around line 506-606: The events array in the response schema for operationId
get_run_events_v1 (path "/api/v1/runs/{runId}/events") is currently unbounded;
update the OpenAPI response to reflect the API behavior by either adding a
maxItems (e.g., maxItems: <limit>) and a note in the description or converting
the response to a paginated shape (e.g., { events: [...], nextCursor: string,
limit: number }) and update the description to document paging semantics; ensure
the change is applied to the response schema for the "200" response under that
path so validators and consumers know the size/cap behavior.
ℹ️ Review info
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/v3-openapi.yaml
📜 Review details
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,ts,jsx,tsx,json,md,yaml,yml}
📄 CodeRabbit inference engine (AGENTS.md)
Format code using Prettier before committing
Files:
docs/v3-openapi.yaml
🧠 Learnings (11)
📓 Common learnings
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToRunsWithTag()` to subscribe to all runs with a specific tag
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToRunsWithTag()` to subscribe to all runs with a specific tag
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-06-06T16:54:23.316Z
Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 2155
File: docs/docs.json:179-183
Timestamp: 2025-06-06T16:54:23.316Z
Learning: In the docs.json configuration for the Trigger.dev documentation (Mintlify system), both "tags": ["v4"] and "tag": "v4" properties can be used together and work correctly, even though this behavior is undocumented and may not work in local development environments.
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Subscribe to run updates using `runs.subscribeToRun()` for realtime monitoring of task execution
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `.withStreams()` to subscribe to realtime streams from task metadata in addition to run changes
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToBatch()` to subscribe to changes for all runs in a batch
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2026-02-19T18:09:16.183Z
Learnt from: samejr
Repo: triggerdotdev/trigger.dev PR: 3095
File: apps/webapp/app/components/navigation/DashboardDialogs.tsx:47-47
Timestamp: 2026-02-19T18:09:16.183Z
Learning: In the triggerdotdev/trigger.dev codebase, the pattern `isPaying === false` is used consistently to explicitly check for free plan users. This is a project convention that distinguishes between `isPaying === true` (paying), `isPaying === false` (free), and `isPaying === undefined` (no subscription data). Do not suggest changing this to negation pattern.
```
<!-- <review_comment_addressed>
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Attach metadata to task runs using the metadata option when triggering, and access/update it inside runs using metadata functions
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Scope idempotency keys globally or to current run using the scope parameter
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties
Applied to files:
docs/v3-openapi.yaml
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `schemaTask()` from `trigger.dev/sdk/v3` with Zod schema for payload validation
Applied to files:
docs/v3-openapi.yaml
🪛 Checkov (3.2.334)
docs/v3-openapi.yaml
[medium] 522-571: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (4)
docs/v3-openapi.yaml (4)
363-444: Add-tags endpoint docs look solid.Request/response shape and SDK/Fetch samples read consistently.
445-505: Trace endpoint schema + sample look consistent.The response model and example align well.
2661-2666: Good reuse of RunTags for task triggers.Nice consolidation to reduce drift across tag definitions.
2423-2486: AddminLength: 1toRunTagschema only; do not changeRunTagsfromoneOfto array-only.The API accepts both single strings and arrays for
RunTags(as shown by the handler at line 48:typeof body.data.tags === "string" ? [body.data.tags] : body.data.tags). The currentoneOfschema is correct and changing it to array-only would break backward compatibility.However, adding
minLength: 1toRunTagis valid—the documentation states tags must be "between 1 and 128 characters," and the handler validates against empty strings (line 51:if (tag.trim().length === 0) return false).Update
RunTagonly:RunTag: type: string minLength: 1 maxLength: 128 description: A single run tag. Must be less than 128 characters. example: "user_123456"Likely an incorrect or invalid review comment.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| description: One or more tags to attach to a run. Runs can have a maximum of 10 tags. | ||
| SpanDetailedSummary: | ||
| type: object | ||
| properties: | ||
| id: | ||
| type: string | ||
| description: The span ID. | ||
| parentId: | ||
| type: string | ||
| nullable: true | ||
| description: The parent span ID, if any. | ||
| runId: | ||
| type: string | ||
| description: The run ID this span belongs to. | ||
| data: | ||
| type: object | ||
| properties: | ||
| message: | ||
| type: string | ||
| description: The span message. | ||
| taskSlug: | ||
| type: string | ||
| description: The task identifier, if applicable. | ||
| startTime: | ||
| type: string | ||
| format: date-time | ||
| description: The start time of the span. | ||
| duration: | ||
| type: number | ||
| description: The duration of the span in nanoseconds. | ||
| isError: | ||
| type: boolean | ||
| isPartial: | ||
| type: boolean | ||
| isCancelled: | ||
| type: boolean | ||
| level: | ||
| type: string | ||
| enum: [TRACE, DEBUG, LOG, INFO, WARN, ERROR] | ||
| attemptNumber: | ||
| type: number | ||
| nullable: true | ||
| properties: | ||
| type: object | ||
| description: Arbitrary OTel attributes attached to the span. | ||
| children: | ||
| type: array | ||
| description: Nested child spans. Each child has the same structure as the parent span. | ||
| items: |
There was a problem hiding this comment.
🚩 SpanDetailedSummary OpenAPI schema omits events field present in actual response
The SpanDetailedSummary OpenAPI schema (docs/v3-openapi.yaml:2437-2485) omits the events field from data, but the actual TypeScript type at apps/webapp/app/v3/eventRepository/eventRepository.types.ts:282-300 includes events: SpanEvents in the data object. Since the trace endpoint (apps/webapp/app/routes/api.v1.runs.$runId.trace.ts) returns the full TraceDetailedSummary object, the events field will be present in the actual response but undocumented. This is not a correctness bug (the API still works), but API consumers relying on the schema won't know about the events data.
Was this helpful? React with 👍 or 👎 to provide feedback.
| type: object | ||
| properties: | ||
| events: | ||
| type: array | ||
| items: | ||
| type: object | ||
| properties: | ||
| spanId: | ||
| type: string | ||
| description: The span ID of the event. | ||
| parentId: | ||
| type: string | ||
| nullable: true | ||
| description: The parent span ID, if any. | ||
| runId: | ||
| type: string | ||
| nullable: true | ||
| description: The run ID associated with this event. | ||
| message: | ||
| type: string | ||
| description: The event message. | ||
| startTime: | ||
| type: string | ||
| description: The start time of the event as a bigint string (nanoseconds since epoch). | ||
| duration: | ||
| type: number | ||
| description: The duration of the event in nanoseconds. | ||
| isError: | ||
| type: boolean | ||
| description: Whether this event represents an error. | ||
| isPartial: | ||
| type: boolean | ||
| description: Whether this event is partial (still in progress). | ||
| isCancelled: | ||
| type: boolean | ||
| description: Whether this event was cancelled. | ||
| level: | ||
| type: string | ||
| enum: [TRACE, DEBUG, LOG, INFO, WARN, ERROR] | ||
| description: The log level of the event. | ||
| kind: | ||
| type: string | ||
| enum: [UNSPECIFIED, INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER, UNRECOGNIZED, LOG] | ||
| description: The kind of span event. | ||
| attemptNumber: | ||
| type: number | ||
| nullable: true | ||
| description: The attempt number this event belongs to. | ||
| taskSlug: | ||
| type: string | ||
| description: The task identifier. |
There was a problem hiding this comment.
🚩 Events endpoint schema also omits events and style fields from response items
The events endpoint OpenAPI schema (docs/v3-openapi.yaml:519-569) documents most fields of RunPreparedEvent but omits the events (SpanEvents) and style (TaskEventStyle) fields that are present in the actual RunPreparedEvent type (apps/webapp/app/v3/eventRepository/eventRepository.types.ts:170-184). The route at apps/webapp/app/routes/api.v1.runs.$runId.events.ts:48-54 returns the full event objects (with a TODO comment about returning only relevant fields). These extra fields will appear in the real response but are undocumented. This is consistent with the TODO at line 45 of the route file suggesting the response shape may be refined later.
Was this helpful? React with 👍 or 👎 to provide feedback.
| "/api/v1/runs/{runId}/tags": | ||
| parameters: | ||
| - $ref: "#/components/parameters/runId" | ||
| post: | ||
| operationId: add_run_tags_v1 | ||
| summary: Add tags to a run | ||
| description: Adds one or more tags to a run. Runs can have a maximum of 10 tags. Duplicate tags are ignored. | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| required: | ||
| - tags | ||
| properties: | ||
| tags: | ||
| $ref: "#/components/schemas/RunTags" | ||
| responses: | ||
| "200": | ||
| description: Successful request | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| message: | ||
| type: string | ||
| example: "Successfully set 2 new tags." | ||
| "400": | ||
| description: Invalid request | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| error: | ||
| type: string | ||
| "401": | ||
| description: Unauthorized request | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| error: | ||
| type: string | ||
| enum: | ||
| - Invalid or Missing API Key | ||
| "422": | ||
| description: Too many tags | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| properties: | ||
| error: | ||
| type: string | ||
| description: Runs can only have 10 tags. | ||
| tags: | ||
| - runs | ||
| security: | ||
| - secretKey: [] | ||
| x-codeSamples: | ||
| - lang: typescript | ||
| label: SDK | ||
| source: |- | ||
| import { runs } from "@trigger.dev/sdk"; | ||
|
|
||
| await runs.addTags("run_1234", ["tag-1", "tag-2"]); | ||
| - lang: typescript | ||
| label: Fetch | ||
| source: |- | ||
| await fetch("https://api.trigger.dev/api/v1/runs/run_1234/tags", { | ||
| method: "POST", | ||
| headers: { | ||
| "Authorization": `Bearer ${process.env.TRIGGER_SECRET_KEY}`, | ||
| "Content-Type": "application/json", | ||
| }, | ||
| body: JSON.stringify({ tags: ["tag-1", "tag-2"] }), | ||
| }); |
There was a problem hiding this comment.
🚩 Tags endpoint lacks 404 response for non-existent runs
The add-tags endpoint OpenAPI spec documents 200, 400, 401, and 422 responses but no 404. Looking at the actual implementation (apps/webapp/app/routes/api.v1.runs.$runId.tags.ts), if the run doesn't exist, getTagsForRunId returns undefined which becomes [] (line 44). Then prisma.taskRun.update at line 82 will throw a Prisma P2025 (record not found) error, which is caught by the catch block and returned as a 500 with the error message. So the API actually returns 500 (not 404) for missing runs — this is arguably a pre-existing issue in the route handler rather than the documentation, since other similar endpoints use createLoaderApiRoute which handles 404 properly.
Was this helpful? React with 👍 or 👎 to provide feedback.
2 participants
Adds API reference pages for three previously undocumented run endpoints: retrieve run events, retrieve run trace, and add tags to a run.