From 093ef191b160447565ddc904ab118b5ec5c9fa12 Mon Sep 17 00:00:00 2001 From: isshaddad Date: Mon, 23 Feb 2026 16:54:46 -0500 Subject: [PATCH 1/5] add GET /api/v1/runs/{runId}/events endpoint --- docs/docs.json | 3 +- docs/management/runs/retrieve-events.mdx | 4 + docs/v3-openapi.yaml | 101 +++++++++++++++++++++++ 3 files changed, 107 insertions(+), 1 deletion(-) create mode 100644 docs/management/runs/retrieve-events.mdx diff --git a/docs/docs.json b/docs/docs.json index 7c52e79b91c..8741a647d80 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -253,7 +253,8 @@ "management/runs/replay", "management/runs/cancel", "management/runs/reschedule", - "management/runs/update-metadata" + "management/runs/update-metadata", + "management/runs/retrieve-events" ] }, { diff --git a/docs/management/runs/retrieve-events.mdx b/docs/management/runs/retrieve-events.mdx new file mode 100644 index 00000000000..7d47b3f9e40 --- /dev/null +++ b/docs/management/runs/retrieve-events.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve run events" +openapi: "v3-openapi GET /api/v1/runs/{runId}/events" +--- diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index 080c20ca0f7..8af21c75d60 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -360,6 +360,107 @@ paths: const handle = await runs.replay("run_1234"); + "/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. + "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" From 9b4fea0959631445288942865eac283bb9f92404 Mon Sep 17 00:00:00 2001 From: isshaddad Date: Mon, 23 Feb 2026 17:12:47 -0500 Subject: [PATCH 2/5] add GET /api/v1/runs/{runId}/trace endpoint --- docs/docs.json | 3 +- docs/management/runs/retrieve-trace.mdx | 4 + docs/v3-openapi.yaml | 110 ++++++++++++++++++++++++ 3 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 docs/management/runs/retrieve-trace.mdx diff --git a/docs/docs.json b/docs/docs.json index 8741a647d80..28feedb705f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -254,7 +254,8 @@ "management/runs/cancel", "management/runs/reschedule", "management/runs/update-metadata", - "management/runs/retrieve-events" + "management/runs/retrieve-events", + "management/runs/retrieve-trace" ] }, { diff --git a/docs/management/runs/retrieve-trace.mdx b/docs/management/runs/retrieve-trace.mdx new file mode 100644 index 00000000000..668718cf76a --- /dev/null +++ b/docs/management/runs/retrieve-trace.mdx @@ -0,0 +1,4 @@ +--- +title: "Retrieve run trace" +openapi: "v3-openapi GET /api/v1/runs/{runId}/trace" +--- diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index 8af21c75d60..41a10bfb1b5 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -360,6 +360,67 @@ paths: const handle = await runs.replay("run_1234"); + "/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" @@ -2277,6 +2338,55 @@ components: configure({ accessToken: "tr_pat_1234" }); ``` schemas: + 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: + type: object TriggerTaskResponse: type: object properties: From 8f00bf4dbd1083ed5802080420a0c5e8deb93aeb Mon Sep 17 00:00:00 2001 From: isshaddad Date: Mon, 23 Feb 2026 17:21:20 -0500 Subject: [PATCH 3/5] add POST /api/v1/runs/{runId}/tags endpoint --- docs/docs.json | 1 + docs/management/runs/add-tags.mdx | 4 ++ docs/v3-openapi.yaml | 90 +++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+) create mode 100644 docs/management/runs/add-tags.mdx diff --git a/docs/docs.json b/docs/docs.json index 28feedb705f..eba59c7be98 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -254,6 +254,7 @@ "management/runs/cancel", "management/runs/reschedule", "management/runs/update-metadata", + "management/runs/add-tags", "management/runs/retrieve-events", "management/runs/retrieve-trace" ] diff --git a/docs/management/runs/add-tags.mdx b/docs/management/runs/add-tags.mdx new file mode 100644 index 00000000000..6e8cdf02919 --- /dev/null +++ b/docs/management/runs/add-tags.mdx @@ -0,0 +1,4 @@ +--- +title: "Add tags to a run" +openapi: "v3-openapi POST /api/v1/runs/{runId}/tags" +--- diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index 41a10bfb1b5..647f158a659 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -360,6 +360,96 @@ 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: + oneOf: + - type: string + description: A single tag to add. + example: "my-tag" + - type: array + description: An array of tags to add. + items: + type: string + example: ["tag-1", "tag-2"] + 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" From 5654c8bea69b11d80de71dfda1303669c0bbee4c Mon Sep 17 00:00:00 2001 From: isshaddad Date: Mon, 23 Feb 2026 18:58:39 -0500 Subject: [PATCH 4/5] coderabbit changes --- docs/v3-openapi.yaml | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index 647f158a659..cd652b203be 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -377,15 +377,7 @@ paths: - tags properties: tags: - oneOf: - - type: string - description: A single tag to add. - example: "my-tag" - - type: array - description: An array of tags to add. - items: - type: string - example: ["tag-1", "tag-2"] + $ref: "#/components/schemas/RunTags" responses: "200": description: Successful request @@ -2428,6 +2420,21 @@ 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: @@ -2476,7 +2483,7 @@ components: type: array description: Nested child spans. Each child has the same structure as the parent span. items: - type: object + $ref: "#/components/schemas/SpanDetailedSummary" TriggerTaskResponse: type: object properties: @@ -2651,18 +2658,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: From ec9b56e2320d2b3b69a19316da6e730abfc910f3 Mon Sep 17 00:00:00 2001 From: isshaddad Date: Tue, 24 Feb 2026 10:45:54 -0500 Subject: [PATCH 5/5] devin changes applied --- docs/v3-openapi.yaml | 51 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/v3-openapi.yaml b/docs/v3-openapi.yaml index cd652b203be..b2b37b2f06b 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -567,6 +567,41 @@ paths: 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: @@ -2479,6 +2514,22 @@ components: 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.