diff --git a/docs/docs.json b/docs/docs.json index 7c52e79b91c..eba59c7be98 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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" ] }, { 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/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/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 080c20ca0f7..b2b37b2f06b 100644 --- a/docs/v3-openapi.yaml +++ b/docs/v3-openapi.yaml @@ -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: