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}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/v3-openapi.yaml`:
- Around line 410-411: Update the 401 error enum for the add-tags operation so
the string matches other entries: change the value "Invalid or Missing API Key"
to "Invalid or Missing API key" (lowercase k) so the enum under the add-tags
endpoint's 401 response is consistent with the other 401 error enum values.
- Around line 521-523: The OpenAPI schema for the events array currently lacks
an upper bound (the "events" property), which triggers Checkov CKV_OPENAPI_21
and may allow unbounded payloads; update the schema for the "events" array by
either adding a sensible maxItems (e.g., maxItems: 10000) to enforce a
server-side cap on returned items or, if no cap exists, add a clear description
on the "events" array indicating that results may be large/unbounded and
documenting any pagination behavior or server limits; modify the "events" array
schema block in docs/v3-openapi.yaml accordingly (adjust the items section to
include maxItems or a description) so the contract explicitly states the limit
or lack thereof.
- Around line 540-542: The OpenAPI schema for the events endpoint defines
startTime with an incorrect description ("bigint string (nanoseconds since
epoch)"); update the startTime property used by RunPreparedEvent[]/QueriedEvent
to match runtime serialization by removing the nanoseconds description and
adding format: date-time (type: string, format: date-time) so it aligns with
other schemas like SpanDetailedSummary and actual ISO 8601 Date serialization.
ℹ️ Review info
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/v3-openapi.yaml
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Mintlify Deployment
🧰 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:23.944Z
Learnt from: samejr
Repo: triggerdotdev/trigger.dev PR: 3095
File: apps/webapp/app/components/navigation/DashboardDialogs.tsx:47-47
Timestamp: 2026-02-19T18:09:23.944Z
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} : 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} : 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 `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-606: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
| enum: | ||
| - Invalid or Missing API Key |
There was a problem hiding this comment.
Fix API Key capitalization — should be API key (lowercase k).
All other 401 error enum values in this spec use "Invalid or Missing API key" (lowercase k): lines 340, 478, 615, 764, etc. The add-tags endpoint uses a capital K, which is inconsistent and could break exact-string-match error handling in clients.
🔧 Proposed fix
enum:
- - Invalid or Missing API Key
+ - Invalid or Missing API key🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/v3-openapi.yaml` around lines 410 - 411, Update the 401 error enum for
the add-tags operation so the string matches other entries: change the value
"Invalid or Missing API Key" to "Invalid or Missing API key" (lowercase k) so
the enum under the add-tags endpoint's 401 response is consistent with the other
401 error enum values.
| events: | ||
| type: array | ||
| items: |
There was a problem hiding this comment.
Add maxItems to the events array or document the absence of a limit.
The events array has no upper bound, which may return unbounded payloads for long-running or highly-instrumented tasks. If the server enforces a cap, document it with maxItems; if not, consider adding a note in the description that results can be large.
This was also flagged by Checkov (CKV_OPENAPI_21).
🔧 Proposed fix (if a server-side limit exists, e.g. 10,000)
events:
type: array
+ maxItems: 10000
items:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/v3-openapi.yaml` around lines 521 - 523, The OpenAPI schema for the
events array currently lacks an upper bound (the "events" property), which
triggers Checkov CKV_OPENAPI_21 and may allow unbounded payloads; update the
schema for the "events" array by either adding a sensible maxItems (e.g.,
maxItems: 10000) to enforce a server-side cap on returned items or, if no cap
exists, add a clear description on the "events" array indicating that results
may be large/unbounded and documenting any pagination behavior or server limits;
modify the "events" array schema block in docs/v3-openapi.yaml accordingly
(adjust the items section to include maxItems or a description) so the contract
explicitly states the limit or lack thereof.
| startTime: | ||
| type: string | ||
| description: The start time of the event as a bigint string (nanoseconds since epoch). |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, examine the YAML file around lines 540-542
sed -n '535,550p' docs/v3-openapi.yamlRepository: triggerdotdev/trigger.dev
Length of output: 885
🏁 Script executed:
# Then examine the YAML file around lines 2495-2498
sed -n '2490,2505p' docs/v3-openapi.yamlRepository: triggerdotdev/trigger.dev
Length of output: 606
🏁 Script executed:
# Search for all startTime definitions in the YAML to understand the full context
rg -n "startTime:" docs/v3-openapi.yaml | head -20Repository: triggerdotdev/trigger.dev
Length of output: 135
🏁 Script executed:
# Get more context to identify which schema/endpoint each startTime belongs to
sed -n '500,542p' docs/v3-openapi.yaml | grep -E "(^[a-zA-Z]|startTime:)" | head -20Repository: triggerdotdev/trigger.dev
Length of output: 103
🏁 Script executed:
# Get more context for the second startTime
sed -n '2450,2500p' docs/v3-openapi.yaml | grep -E "(^[a-zA-Z]|startTime:)" | head -20Repository: triggerdotdev/trigger.dev
Length of output: 91
🏁 Script executed:
# Read section to identify the schema for startTime at line 540
sed -n '480,542p' docs/v3-openapi.yamlRepository: triggerdotdev/trigger.dev
Length of output: 2275
🏁 Script executed:
# Read section to identify the schema for startTime at line 2495
sed -n '2420,2505p' docs/v3-openapi.yamlRepository: triggerdotdev/trigger.dev
Length of output: 3017
🏁 Script executed:
# Search for tests or code that calls the events endpoint
rg -i "get_run_events\|/events" --type ts --type js -A 5 | head -50Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Search for any documentation or comments about the startTime format
rg -i "nanoseconds since epoch|bigint string" -B 2 -A 2Repository: triggerdotdev/trigger.dev
Length of output: 915
🏁 Script executed:
# Check if there are type definitions or implementation files that clarify the format
fd -t f "types\|schema\|interface" -e ts -e js | head -20Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Examine the ClickHouse event repository to see actual serialization
sed -n '1,100p' apps/webapp/app/v3/eventRepository/clickhouseEventRepository.server.tsRepository: triggerdotdev/trigger.dev
Length of output: 3370
🏁 Script executed:
# Search for how SpanDetailedSummary is actually serialized/returned
rg -i "SpanDetailedSummary" --type ts --type js -B 3 -A 10 | head -80Repository: triggerdotdev/trigger.dev
Length of output: 6779
🏁 Script executed:
# Find the events endpoint handler code
rg -i "get_run_events|/api/v1/runs.*events" --type ts --type js -B 5 -A 20 | head -100Repository: triggerdotdev/trigger.dev
Length of output: 1874
🏁 Script executed:
# Search for where events are serialized/returned to the client
rg -i "return.*events\|serialize.*event" apps/webapp/app/v3 --type ts -B 2 -A 5 | head -80Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Look at the actual event structure to see how startTime is handled
rg -i "type.*event\|interface.*event" apps/webapp/app/v3/eventRepository/eventRepository.types.ts -A 15 | head -100Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Search for the server-side route handler
find apps -type f -name "*.ts" -o -name "*.js" | xargs rg -l "get_run_events|/events" | head -10Repository: triggerdotdev/trigger.dev
Length of output: 109
🏁 Script executed:
# Look for routes or handlers
fd -t f "route\|handler" -e ts -e js apps/webapp | head -20Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Search for where events endpoint returns data
rg -i "events.*startTime|startTime.*nanoseconds" --type ts -B 5 -A 5Repository: triggerdotdev/trigger.dev
Length of output: 27998
🏁 Script executed:
# Search for the actual events endpoint route/handler
find apps/webapp -type f \( -name "*.ts" -o -name "*.tsx" \) | xargs rg -l "runId.*events|/api/v1" | head -20Repository: triggerdotdev/trigger.dev
Length of output: 398
🏁 Script executed:
# Look in routes directory
fd -t f "route" apps/webapp/app -e ts -e tsx | head -20Repository: triggerdotdev/trigger.dev
Length of output: 1700
🏁 Script executed:
# Search for any JSON serialization or response formatting for events
rg -i "json.stringify.*event|response.*event" apps/webapp/app/v3 --type ts -B 3 -A 3 | head -60Repository: triggerdotdev/trigger.dev
Length of output: 2177
🏁 Script executed:
# Look for api routes specifically for runs endpoint
fd -t f "api" apps/webapp/app/routes -e ts | xargs grep -l "runs.*events\|/api/v1" 2>/dev/nullRepository: triggerdotdev/trigger.dev
Length of output: 163
🏁 Script executed:
# Search for where events are fetched and returned as JSON
rg -i "getRunEvents\|list.*event" apps/webapp/app/routes --type ts -B 5 -A 10Repository: triggerdotdev/trigger.dev
Length of output: 51
🏁 Script executed:
# Look for any response.json or return statements in api routes
find apps/webapp/app/routes -name "*.ts" -type f | head -10 | xargs cat | grep -A 10 "json\|events" | head -40Repository: triggerdotdev/trigger.dev
Length of output: 1378
🏁 Script executed:
# Try searching for files containing both "runs" and "events" in routes
find apps/webapp/app/routes -type f -name "*.ts" | xargs grep -l "events" 2>/dev/null | head -10Repository: triggerdotdev/trigger.dev
Length of output: 185
🏁 Script executed:
# Search for the actual route file by pattern matching
fd "runs" apps/webapp/app/routes -e ts | head -20Repository: triggerdotdev/trigger.dev
Length of output: 1232
🏁 Script executed:
# Try a broader search for where events are formatted/returned
rg -i "startTime.*string|nanosecond.*event" apps/webapp --type ts -B 3 -A 3 | head -80Repository: triggerdotdev/trigger.dev
Length of output: 7356
🏁 Script executed:
# Read the events endpoint handler
cat apps/webapp/app/routes/api.v1.runs.$runId.events.tsRepository: triggerdotdev/trigger.dev
Length of output: 146
🏁 Script executed:
# Find and read the events endpoint file
fd "events.ts" apps/webapp/app/routes | xargs catRepository: triggerdotdev/trigger.dev
Length of output: 1982
🏁 Script executed:
# Search for getRunEvents implementation
rg -i "getRunEvents" apps/webapp --type ts -B 2 -A 15 | head -100Repository: triggerdotdev/trigger.dev
Length of output: 8723
🏁 Script executed:
# Search for RunPreparedEvent type definition
rg -i "type.*RunPreparedEvent|interface.*RunPreparedEvent" apps/webapp --type ts -A 20 | head -80Repository: triggerdotdev/trigger.dev
Length of output: 4575
🏁 Script executed:
# Search for PreparedEvent type definition
rg -i "type.*PreparedEvent|interface.*PreparedEvent" apps/webapp --type ts -A 25 | head -100Repository: triggerdotdev/trigger.dev
Length of output: 6508
🏁 Script executed:
# Verify QueriedEvent type definition to confirm startTime is Date
rg -i "type.*QueriedEvent|interface.*QueriedEvent" apps/webapp/app/v3/eventRepository/eventRepository.types.ts -A 30Repository: triggerdotdev/trigger.dev
Length of output: 1659
Fix OpenAPI spec: events endpoint startTime should declare format: date-time, not "bigint string (nanoseconds since epoch)"
The inconsistency is real. Both endpoints serialize startTime as ISO 8601 date-time strings, but the OpenAPI spec at line 540 incorrectly describes it as a nanoseconds bigint string. The events endpoint returns RunPreparedEvent[], which has startTime: Date (inherited from QueriedEvent). When serialized to JSON, JavaScript Date objects become ISO 8601 strings—matching the format: date-time declared at line 2495 for SpanDetailedSummary. Update line 540 to remove the misleading nanoseconds description, add format: date-time, and align the documentation with actual behavior.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/v3-openapi.yaml` around lines 540 - 542, The OpenAPI schema for the
events endpoint defines startTime with an incorrect description ("bigint string
(nanoseconds since epoch)"); update the startTime property used by
RunPreparedEvent[]/QueriedEvent to match runtime serialization by removing the
nanoseconds description and adding format: date-time (type: string, format:
date-time) so it aligns with other schemas like SpanDetailedSummary and actual
ISO 8601 Date serialization.
2 participants
Adds API reference pages for three previously undocumented run endpoints: retrieve run events, retrieve run trace, and add tags to a run.