github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: document undocumented run API endpoints (#3120)

Browse Source 
Adds API reference pages for three previously undocumented run
endpoints: retrieve run events, retrieve run trace, and add tags to a
run.
This commit is contained in:
Iss
2026-02-24 10:49:39 -05:00
committed by GitHub
parent b60788df82
commit 97bf89873e
5 changed files with 378 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/docs.json
+4 -1
View File
@@ -253,7 +253,10 @@
"management/runs/replay",
"management/runs/cancel",
"management/runs/reschedule",
"management/runs/update-metadata"
"management/runs/update-metadata",
"management/runs/add-tags",
"management/runs/retrieve-events",
"management/runs/retrieve-trace"
]
},
{
docs/management/runs/add-tags.mdx
+4
View File
@@ -0,0 +1,4 @@
---
title: "Add tags to a run"
openapi: "v3-openapi POST /api/v1/runs/{runId}/tags"
---
docs/management/runs/retrieve-events.mdx
+4
View File
@@ -0,0 +1,4 @@
---
title: "Retrieve run events"
openapi: "v3-openapi GET /api/v1/runs/{runId}/events"
---
docs/management/runs/retrieve-trace.mdx
+4
View File
@@ -0,0 +1,4 @@
---
title: "Retrieve run trace"
openapi: "v3-openapi GET /api/v1/runs/{runId}/trace"
---
docs/v3-openapi.yaml
+362 -7
View File
@@ -360,6 +360,285 @@ paths:
const handle = await runs.replay("run_1234");
"/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"] }),
});
"/api/v1/runs/{runId}/trace":
parameters:
- $ref: "#/components/parameters/runId"
get:
operationId: get_run_trace_v1
summary: Retrieve run trace
description: Returns the full OTel trace tree for a run, including all spans and their children.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
trace:
type: object
properties:
traceId:
type: string
description: The OTel trace ID.
rootSpan:
$ref: "#/components/schemas/SpanDetailedSummary"
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Run not found
- Trace not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/trace", {
headers: {
Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
},
});
const { trace } = await response.json();
"/api/v1/runs/{runId}/events":
parameters:
- $ref: "#/components/parameters/runId"
get:
operationId: get_run_events_v1
summary: Retrieve run events
description: Returns all OTel span events for a run. Useful for debugging and observability.
responses:
"200":
description: Successful request
content:
application/json:
schema:
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.
events:
type: array
description: Span events (e.g. exceptions, cancellations) that occurred during this event.
items:
type: object
properties:
name:
type: string
description: The event name (e.g. "exception", "cancellation", "attempt_failed").
time:
type: string
format: date-time
description: The time the event occurred.
properties:
type: object
description: Event-specific properties.
style:
type: object
description: Display style metadata for the event.
properties:
icon:
type: string
description: Icon identifier for display.
variant:
type: string
description: Visual variant (e.g. "success", "failure").
accessory:
type: object
description: Accessory display element.
properties:
text:
type: string
style:
type: string
enum: [codepath]
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Run not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/events", {
headers: {
Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
},
});
const { events } = await response.json();
"/api/v1/runs/{runId}/metadata":
parameters:
- $ref: "#/components/parameters/runId"
@@ -2176,6 +2455,86 @@ components:
configure({ accessToken: "tr_pat_1234" });
```
schemas:
RunTag:
type: string
maxLength: 128
description: A single run tag. Must be less than 128 characters.
example: "user_123456"
RunTags:
oneOf:
- $ref: "#/components/schemas/RunTag"
- type: array
items:
$ref: "#/components/schemas/RunTag"
maxItems: 10
uniqueItems: true
example: ["user_123456", "product_4629101"]
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.
events:
type: array
description: Span events (e.g. exceptions, cancellations) that occurred during this span.
items:
type: object
properties:
name:
type: string
description: The event name (e.g. "exception", "cancellation", "attempt_failed").
time:
type: string
format: date-time
description: The time the event occurred.
properties:
type: object
description: Event-specific properties.
children:
type: array
description: Nested child spans. Each child has the same structure as the parent span.
items:
$ref: "#/components/schemas/SpanDetailedSummary"
TriggerTaskResponse:
type: object
properties:
@@ -2350,18 +2709,14 @@ components:
delay:
$ref: "#/components/schemas/Delay"
tags:
type:
- array
- string
example: ["user_123456", "product_4629101"]
allOf:
- $ref: "#/components/schemas/RunTags"
description: |
Tags to attach to the run. Tags can be used to filter runs in the dashboard and using the SDK.
You can set up to 5 tags per run, they must be less than 64 characters each.
You can set up to 10 tags per run, each must be less than 128 characters.
We recommend prefixing tags with a namespace using an underscore or colon, like `user_1234567` or `org:9876543`. Stripe uses underscores.
items:
type: string
machine:
type: string
enum: