v3-openapi.yaml

---
openapi: 3.1.0
info:
  title: Trigger.dev v3 REST API
  description: "The REST API lets you trigger and manage runs on Trigger.dev. You
    can trigger a run, get the status of a run, and get the results of a run. "
  version: 2024-04
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.trigger.dev
    description: Trigger.dev API
paths:
  "/api/v1/schedules":
    post:
      operationId: create_schedule_v1
      summary: Create a schedule
      description: Create a new `IMPERATIVE` schedule based on the specified options.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateScheduleOptions"
      responses:
        "200":
          description: Schedule created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ScheduleObject"
        "400":
          description: Invalid request parameters
        "401":
          description: Unauthorized
        "422":
          description: Unprocessable Entity
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const schedule = await schedules.create({
              task: 'my-task',
              cron: '0 0 * * *'
              deduplicationKey: 'my-schedule',
              timezone: 'America/New_York'
            });

    get:
      operationId: list_schedules_v1
      summary: List all schedules
      description: List all schedules. You can also paginate the results.
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          required: false
          description: Page number of the schedule listing
        - in: query
          name: perPage
          schema:
            type: integer
          required: false
          description: Number of schedules per page
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListSchedulesResult"
        "401":
          description: Unauthorized request
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const allSchedules = await schedules.list();

  "/api/v1/schedules/{schedule_id}":
    get:
      operationId: get_schedule_v1
      summary: Retrieve Schedule
      description: Get a schedule by its ID.
      parameters:
        - in: path
          name: schedule_id
          required: true
          schema:
            type: string
          description: The ID of the schedule.
          example: sched_1234
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ScheduleObject"
        "401":
          description: Unauthorized request
        "404":
          description: Resource not found
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const schedule = await schedules.retrieve(scheduleId);

    put:
      operationId: update_schedule_v1
      summary: Update Schedule
      description: Update a schedule by its ID. This will only work on `IMPERATIVE` schedules that were created in the dashboard or using the imperative SDK functions like `schedules.create()`.
      parameters:
        - in: path
          name: schedule_id
          required: true
          schema:
            type: string
          description: The ID of the schedule.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateScheduleOptions"
      responses:
        "200":
          description: Schedule updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ScheduleObject"
        "400":
          description: Invalid request parameters
        "401":
          description: Unauthorized
        "404":
          description: Resource not found
        "422":
          description: Unprocessable Entity
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const updatedSchedule = await schedules.update(scheduleId, {
              task: 'my-updated-task',
              cron: '0 0 * * *'
            });

    delete:
      operationId: delete_schedule_v1
      summary: Delete Schedule
      description: Delete a schedule by its ID. This will only work on `IMPERATIVE` schedules that were created in the dashboard or using the imperative SDK functions like `schedules.create()`.
      parameters:
        - in: path
          name: schedule_id
          required: true
          schema:
            type: string
          description: The ID of the schedule.
      responses:
        "200":
          description: Schedule deleted successfully
        "401":
          description: Unauthorized request
        "404":
          description: Resource not found
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            await schedules.del(scheduleId);

  "/api/v1/schedules/{schedule_id}/deactivate":
    post:
      operationId: deactivate_schedule_v1
      summary: Deactivate Schedule.
      description: Deactivate a schedule by its ID. This will only work on `IMPERATIVE` schedules that were created in the dashboard or using the imperative SDK functions like `schedules.create()`.
      parameters:
        - in: path
          name: schedule_id
          required: true
          schema:
            type: string
          description: The ID of the schedule.
      responses:
        "200":
          description: Schedule updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ScheduleObject"
        "401":
          description: Unauthorized request
        "404":
          description: Resource not found
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const schedule = await schedules.deactivate(scheduleId);

  "/api/v1/schedules/{schedule_id}/activate":
    post:
      operationId: activate_schedule_v1
      summary: Activate Schedule
      description: Activate a schedule by its ID. This will only work on `IMPERATIVE` schedules that were created in the dashboard or using the imperative SDK functions like `schedules.create()`.
      parameters:
        - in: path
          name: schedule_id
          required: true
          schema:
            type: string
          description: The ID of the schedule.
      responses:
        "200":
          description: Schedule updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ScheduleObject"
        "401":
          description: Unauthorized request
        "404":
          description: Resource not found
      tags:
        - schedules
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const schedule = await schedules.activate(scheduleId);

  "/api/v1/timezones":
    get:
      security: []
      operationId: get_timezones_v1
      summary: Get all supported timezones
      description: Get all supported timezones that schedule tasks support.
      parameters:
        - in: query
          name: excludeUtc
          schema:
            type: boolean
          required: false
          description: Defaults to false. Whether to include UTC in the results or not.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/GetTimezonesResult"
      tags:
        - schedules
      x-codeSamples:
        - lang: typescript
          source: |-
            import { schedules } from "@trigger.dev/sdk";

            const { timezones } = await schedules.timezones();

  "/api/v1/runs/{runId}/replay":
    parameters:
      - $ref: "#/components/parameters/runId"
    post:
      operationId: replay_run_v1
      summary: Replay a run
      description: Creates a new run with the same payload and options as the original
        run.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the new run.
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Invalid or missing run ID
                      - Failed to create new run
        "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: |-
            import { runs } from "@trigger.dev/sdk";

            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"
    put:
      operationId: update_run_metadata_v1
      summary: Update run metadata
      description: Update the metadata of a run.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  description: The new metadata to set on the run.
                  example: { key: "value" }
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: object
                    description: The updated metadata of the run.
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Invalid or missing run ID
                      - Invalid metadata
        "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:
                      - Task Run not found
      tags:
        - runs
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: Save metadata
          source: |-
            import { metadata, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                await metadata.save({ key: "value" });
              }
            });

  "/api/v2/runs/{runId}/cancel":
    parameters:
      - $ref: "#/components/parameters/runId"
    post:
      operationId: cancel_run_v1
      summary: Cancel a run
      description: Cancels an in-progress run. If the run is already completed, this
        will have no effect.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the run that was canceled.
                    example: run_1234
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Invalid or missing run ID
                      - Failed to create new run
        "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: |-
            import { runs } from "@trigger.dev/sdk";

            await runs.cancel("run_1234");

  "/api/v1/deployments":
    get:
      operationId: list_deployments_v1
      summary: List deployments
      description: List deployments for the authenticated environment, ordered by most recent first.
      parameters:
        - in: query
          name: "page[after]"
          schema:
            type: string
          description: The deployment ID to start the search from, to get the next page.
        - in: query
          name: "page[size]"
          schema:
            type: integer
            minimum: 5
            maximum: 100
            default: 20
          description: The number of deployments to return (default 20, min 5, max 100).
        - in: query
          name: status
          schema:
            type: string
            enum:
              [
                "PENDING",
                "BUILDING",
                "DEPLOYING",
                "DEPLOYED",
                "FAILED",
                "CANCELED",
                "TIMED_OUT",
              ]
          description: Filter deployments by status.
        - in: query
          name: period
          schema:
            type: string
          description: Filter deployments created within this period (e.g. 1d, 7d, 3h).
        - in: query
          name: from
          schema:
            type: string
          description: Filter deployments created on or after this date (ISO 8601).
        - in: query
          name: to
          schema:
            type: string
          description: Filter deployments created on or before this date (ISO 8601). Only applied when `from` is also provided.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The deployment ID
                        createdAt:
                          type: string
                          format: date-time
                          description: When the deployment was created
                        shortCode:
                          type: string
                          description: The short code for the deployment
                        version:
                          type: string
                          description: The deployment version (e.g., "20250228.1")
                        runtime:
                          type: string
                          nullable: true
                          description: The runtime used (e.g., "node")
                        runtimeVersion:
                          type: string
                          nullable: true
                          description: The runtime version
                        status:
                          type: string
                          enum:
                            [
                              "PENDING",
                              "BUILDING",
                              "DEPLOYING",
                              "DEPLOYED",
                              "FAILED",
                              "CANCELED",
                              "TIMED_OUT",
                            ]
                          description: The current status of the deployment
                        deployedAt:
                          type: string
                          format: date-time
                          nullable: true
                          description: When the deployment was promoted to DEPLOYED
                        git:
                          type: object
                          nullable: true
                          description: Git metadata associated with the deployment
                        error:
                          type: object
                          nullable: true
                          description: Error data if the deployment failed
                  pagination:
                    type: object
                    properties:
                      next:
                        type: string
                        description: Cursor for the next page. Pass as `page[after]` to get the next page. Omitted if there are no more results.
        "401":
          description: Unauthorized - Access token is missing or invalid
      tags:
        - deployments
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            const response = await fetch(
              "https://api.trigger.dev/api/v1/deployments",
              {
                method: "GET",
                headers: {
                  "Authorization": `Bearer ${secretKey}`,
                },
              }
            );
            const { data, pagination } = await response.json();
        - lang: curl
          source: |-
            curl -X GET "https://api.trigger.dev/api/v1/deployments" \
              -H "Authorization: Bearer tr_dev_1234"

  "/api/v1/deployments/{deploymentId}":
    parameters:
      - in: path
        name: deploymentId
        required: true
        schema:
          type: string
        description: The deployment ID.
    get:
      operationId: get_deployment_v1
      summary: Get deployment
      description: Retrieve information about a specific deployment by its ID.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The deployment ID
                  status:
                    type: string
                    enum:
                      [
                        "PENDING",
                        "INSTALLING",
                        "BUILDING",
                        "DEPLOYING",
                        "DEPLOYED",
                        "FAILED",
                        "CANCELED",
                        "TIMED_OUT",
                      ]
                    description: The current status of the deployment
                  contentHash:
                    type: string
                    description: Hash of the deployment content
                  shortCode:
                    type: string
                    description: The short code for the deployment
                  version:
                    type: string
                    description: The deployment version (e.g., "20250228.1")
                  imageReference:
                    type: string
                    nullable: true
                    description: Reference to the deployment image
                  imagePlatform:
                    type: string
                    description: Platform of the deployment image
                  externalBuildData:
                    type: object
                    nullable: true
                    description: External build data if applicable
                  errorData:
                    type: object
                    nullable: true
                    description: Error data if the deployment failed
                  worker:
                    type: object
                    nullable: true
                    description: Worker information if available
                    properties:
                      id:
                        type: string
                      version:
                        type: string
                      tasks:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            slug:
                              type: string
                            filePath:
                              type: string
                            exportName:
                              type: string
        "401":
          description: Unauthorized - Access token is missing or invalid
        "404":
          description: Deployment not found
      tags:
        - deployments
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            const response = await fetch(
              `https://api.trigger.dev/api/v1/deployments/${deploymentId}`,
              {
                method: "GET",
                headers: {
                  "Authorization": `Bearer ${secretKey}`,
                },
              }
            );
            const deployment = await response.json();
        - lang: curl
          source: |-
            curl -X GET "https://api.trigger.dev/api/v1/deployments/deployment_1234" \
              -H "Authorization: Bearer tr_dev_1234"

  "/api/v1/deployments/latest":
    get:
      operationId: get_latest_deployment_v1
      summary: Get latest deployment
      description: Retrieve information about the latest unmanaged deployment for the authenticated project.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The deployment ID
                  status:
                    type: string
                    enum:
                      [
                        "PENDING",
                        "INSTALLING",
                        "BUILDING",
                        "DEPLOYING",
                        "DEPLOYED",
                        "FAILED",
                        "CANCELED",
                        "TIMED_OUT",
                      ]
                    description: The current status of the deployment
                  contentHash:
                    type: string
                    description: Hash of the deployment content
                  shortCode:
                    type: string
                    description: The short code for the deployment
                  version:
                    type: string
                    description: The deployment version (e.g., "20250228.1")
                  imageReference:
                    type: string
                    nullable: true
                    description: Reference to the deployment image
                  errorData:
                    type: object
                    nullable: true
                    description: Error data if the deployment failed
        "401":
          description: Unauthorized - API key is missing or invalid
        "404":
          description: No deployment found
      tags:
        - deployments
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            const response = await fetch(
              "https://api.trigger.dev/api/v1/deployments/latest",
              {
                method: "GET",
                headers: {
                  "Authorization": `Bearer ${secretKey}`,
                },
              }
            );
            const deployment = await response.json();
        - lang: curl
          source: |-
            curl -X GET "https://api.trigger.dev/api/v1/deployments/latest" \
              -H "Authorization: Bearer tr_dev_1234"

  "/api/v1/deployments/{version}/promote":
    parameters:
      - in: path
        name: version
        required: true
        schema:
          type: string
        description: The deployment version to promote (e.g., "20250228.1").
    post:
      operationId: promote_deployment_v1
      summary: Promote deployment
      description: Promote a previously deployed version to be the current version for the environment. This makes the specified version active for new task runs.
      responses:
        "200":
          description: Deployment promoted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The deployment ID
                  version:
                    type: string
                    description: The deployment version (e.g., "20250228.1")
                  shortCode:
                    type: string
                    description: The short code for the deployment
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "401":
          description: Unauthorized - API key is missing or invalid
        "404":
          description: Deployment not found
      tags:
        - deployments
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            const response = await fetch(
              `https://api.trigger.dev/api/v1/deployments/${version}/promote`,
              {
                method: "POST",
                headers: {
                  "Authorization": `Bearer ${secretKey}`,
                  "Content-Type": "application/json",
                },
              }
            );
            const result = await response.json();
        - lang: curl
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/deployments/20250228.1/promote" \
              -H "Authorization: Bearer tr_dev_1234" \
              -H "Content-Type: application/json"

  "/api/v1/query":
    post:
      operationId: execute_query_v1
      summary: Execute a TRQL query
      description: Execute a TRQL (Trigger.dev Query Language) query against your run data. TRQL is a SQL-style query language that allows you to analyze runs, calculate metrics, and export data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExecuteQueryRequestBody"
      responses:
        "200":
          description: Query executed successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExecuteQueryResponse"
        "400":
          description: Invalid query or request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message describing the query error
        "401":
          description: Unauthorized - API key is missing or invalid
        "500":
          description: Internal server error during query execution
      tags:
        - query
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: SDK - Basic query
          source: |-
            import { query } from "@trigger.dev/sdk";

            // Basic query with defaults (environment scope, json format)
            const result = await query.execute(
              "SELECT run_id, status FROM runs LIMIT 10"
            );
            console.log(result.results);
        - lang: typescript
          label: SDK - Type-safe query
          source: |-
            import { query, type QueryTable } from "@trigger.dev/sdk";

            // Type-safe query using QueryTable
            const result = await query.execute<
              QueryTable<"runs", "run_id" | "status" | "triggered_at">
            >(
              "SELECT run_id, status, triggered_at FROM runs LIMIT 10"
            );

            result.results.forEach(row => {
              console.log(row.run_id, row.status); // Fully typed!
            });
        - lang: typescript
          label: SDK - With options
          source: |-
            import { query } from "@trigger.dev/sdk";

            const result = await query.execute(
              "SELECT COUNT(*) as count FROM runs WHERE status = 'Failed'",
              {
                scope: "project",       // Query across all environments
                period: "7d",           // Last 7 days
                format: "json"
              }
            );
        - lang: typescript
          label: SDK - CSV export
          source: |-
            import { query } from "@trigger.dev/sdk";

            const csvResult = await query.execute(
              "SELECT run_id, status, triggered_at FROM runs",
              {
                format: "csv",
                period: "30d"
              }
            );

            // csvResult.results is a CSV string
            const lines = csvResult.results.split('\n');
        - lang: curl
          label: cURL - Basic query
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/query" \
              -H "Authorization: Bearer tr_dev_1234" \
              -H "Content-Type: application/json" \
              -d '{
                "query": "SELECT run_id, status FROM runs LIMIT 10",
                "scope": "environment",
                "period": "7d",
                "format": "json"
              }'
        - lang: curl
          label: cURL - Aggregation query
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/query" \
              -H "Authorization: Bearer tr_dev_1234" \
              -H "Content-Type: application/json" \
              -d '{
                "query": "SELECT task_identifier, count() as runs, countIf(status = '\''Failed'\'') as failures FROM runs GROUP BY task_identifier",
                "scope": "environment",
                "from": "2024-01-01T00:00:00Z",
                "to": "2024-01-31T23:59:59Z",
                "format": "json"
              }'

  "/api/v1/runs/{runId}/reschedule":
    parameters:
      - $ref: "#/components/parameters/runId"
    post:
      operationId: reschedule_run_v1
      summary: Rescheduled a delayed run
      description: Updates a delayed run with a new delay. Only valid when the run is in the DELAYED state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RescheduleRunRequestBody"
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RetrieveRunResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Invalid or missing run ID
                      - Failed to create new run
        "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: |-
            import { runs } from "@trigger.dev/sdk";

            const handle = await runs.reschedule("run_1234", { delay: new Date("2024-06-29T20:45:56.340Z") });

  "/api/v1/runs/{runId}/result":
    parameters:
      - $ref: "#/components/parameters/runId"
    get:
      operationId: get_run_result_v1
      summary: Retrieve run result
      description: Returns the execution result of a completed run. Returns 404 if the run doesn't exist or hasn't finished yet.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                required: [ok, id]
                properties:
                  ok:
                    type: boolean
                    description: Whether the run completed successfully.
                  id:
                    type: string
                    description: The run ID.
                  output:
                    type: string
                    description: The serialized output as a string (present when ok is true). Use outputType to determine how to parse it — for "application/json" use JSON.parse().
                  outputType:
                    type: string
                    description: The content type of the serialized output, e.g. "application/json".
                  error:
                    type: object
                    description: Error details (present when ok is false).
                  usage:
                    type: object
                    description: Execution usage stats.
                    properties:
                      durationMs:
                        type: number
                        description: Duration of the run in milliseconds.
                  taskIdentifier:
                    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: Run not found or not yet finished
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Run either doesn't exist or is not finished
      tags:
        - runs
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: Fetch
          source: |-
            const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/result", {
              headers: {
                "Authorization": `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
              },
            });
            const result = await response.json();

  "/api/v3/runs/{runId}":
    parameters:
      - $ref: "#/components/parameters/runId"
    get:
      operationId: retrieve_run_v1
      summary: Retrieve a run
      description: |
        Retrieve information about a run, including its status, payload, output, and attempts. If you authenticate with a Public API key, we will omit the payload and output fields for security reasons.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/RetrieveRunResponse"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Invalid or missing run ID
        "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:
        - run
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { runs } from "@trigger.dev/sdk";

            const result = await runs.retrieve("run_1234");

            // We include boolean helpers to check the status of the run
            // (isSuccess, isFailed, isCompleted, etc.)
            if (result.isSuccess) {
              console.log("Run was successful with output", result.output);
            }

            // You also have access to the run status that includes more granular information
            console.log("Run status:", result.status);

            // You can access the payload and output
            console.log("Payload:", result.payload);
            console.log("Output:", result.output);

            // You can also access the attempts, which will give you information about errors (if they exist)
            for (const attempt of result.attempts) {
              if (attempt.status === "FAILED") {
                console.log("Attempt failed with error:", attempt.error);
              }
            }

  "/api/v1/runs":
    get:
      operationId: list_runs_v1
      summary: List runs
      description: List runs in a specific environment. You can filter the runs by status, created at, task identifier, version, and more.
      parameters:
        - $ref: "#/components/parameters/cursorPagination"
        - $ref: "#/components/parameters/runsFilter"
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRunsResult"
        "400":
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorWithDetailsResponse"
        "401":
          description: Unauthorized request
      tags:
        - runs
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: List runs
          source: |-
            import { runs } from "@trigger.dev/sdk";

            // Get the first page of runs
            let page = await runs.list({ limit: 20 });

            for (const run of page.data) {
              console.log(`Run ID: ${run.id}, Status: ${run.status}`);
            }

            // Convenience methods are provided for manually paginating:
            while (page.hasNextPage()) {
              page = await page.getNextPage();
              // Do something with the next page of runs
            }

            // Auto-paginate through all runs
            const allRuns = [];

            for await (const run of runs.list({ limit: 20 })) {
              allRuns.push(run);
            }
        - lang: typescript
          label: Filter runs
          source: |-
            import { runs } from "@trigger.dev/sdk";

            const response = await runs.list({
              status: ["QUEUED", "EXECUTING"],
              taskIdentifier: ["my-task", "my-other-task"],
              from: new Date("2024-04-01T00:00:00Z"),
              to: new Date(),
            });

            for (const run of response.data) {
              console.log(`Run ID: ${run.id}, Status: ${run.status}`);
            }

  "/api/v1/projects/{projectRef}/runs":
    parameters:
      - $ref: "#/components/parameters/projectRef"
    get:
      operationId: list_project_runs_v1
      summary: List project runs
      description: List runs in a project, across multiple environments, using Personal Access Token auth. You can filter the runs by status, created at, task identifier, version, and more.
      parameters:
        - $ref: "#/components/parameters/cursorPagination"
        - $ref: "#/components/parameters/runsFilterWithEnv"
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRunsResult"
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorWithDetailsResponse"
        "401":
          description: Unauthorized request
      tags:
        - runs
      security:
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: List runs
          source: |-
            import { runs, configure } from "@trigger.dev/sdk";

            configure({
              accessToken: "tr_pat_1234" // always use an environment variable for this
            });

            // Get the first page of runs
            let page = await runs.list("proj_1234", { limit: 20 });

            for (const run of page.data) {
              console.log(`Run ID: ${run.id}, Status: ${run.status}`);
            }

            // Convenience methods are provided for manually paginating:
            while (page.hasNextPage()) {
              page = await page.getNextPage();
              // Do something with the next page of runs
            }

            // Auto-paginate through all runs
            const allRuns = [];

            for await (const run of runs.list("proj_1234", { limit: 20 })) {
              allRuns.push(run);
            }
        - lang: typescript
          label: Filter runs
          source: |-
            import { runs, configure } from "@trigger.dev/sdk";

            configure({
              accessToken: "tr_pat_1234" // always use an environment variable for this
            });

            const response = await runs.list("proj_1234", {
              env: ["prod", "staging"],
              status: ["QUEUED", "EXECUTING"],
              taskIdentifier: ["my-task", "my-other-task"],
              from: new Date("2024-04-01T00:00:00Z"),
              to: new Date(),
            });

            for (const run of response.data) {
              console.log(`Run ID: ${run.id}, Status: ${run.status}`);
            }

  "/api/v1/projects/{projectRef}/envvars/{env}":
    parameters:
      - $ref: "#/components/parameters/projectRef"
      - $ref: "#/components/parameters/env"
    get:
      operationId: list_project_envvars_v1
      summary: List environment variables
      description: List all environment variables for a specific project and environment.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListEnvironmentVariablesResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Outside of a task
          source: |-
            import { envvars, configure } from "@trigger.dev/sdk";

            const variables = await envvars.list("proj_yubjwjsfkxnylobaqvqz", "dev");

            for (const variable of variables) {
              console.log(`Name: ${variable.name}, Value: ${variable.value}`);
            }
        - lang: typescript
          label: Inside a task
          source: |-
            import { envvars, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                // projectRef and env are automatically inferred from the task context
                const variables = await envvars.list();

                for (const variable of variables) {
                  console.log(`Name: ${variable.name}, Value: ${variable.value}`);
                }
              }
            })
    post:
      operationId: create_project_envvar_v1
      summary: Create environment variable
      description: Create a new environment variable for a specific project and environment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EnvVar"
      responses:
        "200":
          description: Environment variable created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SucceedResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InvalidEnvVarsRequestResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Outside of a task
          source: |-
            import { envvars } from "@trigger.dev/sdk";

            await envvars.create("proj_yubjwjsfkxnylobaqvqz", "dev", {
              name: "SLACK_API_KEY",
              value: "slack_123456"
            });
        - lang: typescript
          label: Inside a task
          source: |-
            import { envvars, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                // projectRef and env are automatically inferred from the task context
                await envvars.create({
                  name: "SLACK_API_KEY",
                  value: "slack_123456"
                });
              }
            })

  "/api/v1/projects/{projectRef}/envvars/{env}/import":
    parameters:
      - $ref: "#/components/parameters/projectRef"
      - $ref: "#/components/parameters/env"
    post:
      operationId: upload_project_envvars_v1
      summary: Upload environment variables
      description: Upload mulitple environment variables for a specific project and environment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: array
                  items:
                    "$ref": "#/components/schemas/EnvVar"
                override:
                  type: boolean
                  description: Whether to override existing variables or not
                  default: false
              required: ["variables"]

      responses:
        "200":
          description: Environment variables imported successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SucceedResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InvalidEnvVarsRequestResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Import variables from an array
          source: |-
            import { envvars } from "@trigger.dev/sdk";

            await envvars.upload("proj_yubjwjsfkxnylobaqvqz", "dev", {
              variables: { SLACK_API_KEY: "slack_key_1234" },
              override: false
            });

  "/api/v1/projects/{projectRef}/envvars/{env}/{name}":
    parameters:
      - $ref: "#/components/parameters/projectRef"
      - $ref: "#/components/parameters/env"
      - $ref: "#/components/parameters/envvarName"
    get:
      operationId: get_project_envvar_v1
      summary: Retrieve environment variable
      description: Retrieve a specific environment variable for a specific project and environment.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/EnvVarValue"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Outside of a task
          source: |-
            import { envvars } from "@trigger.dev/sdk";

            const variable = await envvars.retrieve("proj_yubjwjsfkxnylobaqvqz", "dev", "SLACK_API_KEY");

            console.log(`Value: ${variable.value}`);
        - lang: typescript
          label: Inside a task
          source: |-
            import { envvars, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                // projectRef and env are automatically inferred from the task context
                const variable = await envvars.retrieve("SLACK_API_KEY");

                console.log(`Value: ${variable.value}`);
              }
            })

    delete:
      operationId: delete_project_envvar_v1
      summary: Delete environment variable
      description: Delete a specific environment variable for a specific project and environment.
      responses:
        "200":
          description: Environment variable deleted successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SucceedResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Outside of a task
          source: |-
            import { envvars } from "@trigger.dev/sdk";

            await envvars.del("proj_yubjwjsfkxnylobaqvqz", "dev", "SLACK_API_KEY");
        - lang: typescript
          label: Inside a task
          source: |-
            import { envvars, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                // projectRef and env are automatically inferred from the task context
                await envvars.del("SLACK_API_KEY");
              }
            })
    put:
      operationId: update_project_envvar_v1
      summary: Update environment variable
      description: Update a specific environment variable for a specific project and environment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/EnvVarValue"
      responses:
        "200":
          description: Environment variable updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SucceedResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/InvalidEnvVarsRequestResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - envvars
      security:
        - secretKey: []
        - personalAccessToken: []
      x-codeSamples:
        - lang: typescript
          label: Outside of a task
          source: |-
            import { envvars } from "@trigger.dev/sdk";

            await envvars.update("proj_yubjwjsfkxnylobaqvqz", "dev", "SLACK_API_KEY", {
              value: "slack_123456"
            });
        - lang: typescript
          label: Inside a task
          source: |-
            import { envvars, task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async () => {
                // projectRef and env are automatically inferred from the task context
                await envvars.update("SLACK_API_KEY", {
                  value: "slack_123456"
                });
              }
            })
  "/api/v1/tasks/{taskIdentifier}/trigger":
    parameters:
      - $ref: "#/components/parameters/taskIdentifier"
    post:
      operationId: trigger_task_v1
      summary: Trigger a task
      description: Trigger a task by its identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TriggerTaskRequestBody"
      responses:
        "200":
          description: Task triggered successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TriggerTaskResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - tasks
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { task } from "@trigger.dev/sdk";

            export const myTask = await task({
              id: "my-task",
              run: async (payload: { message: string }) => {
                console.log("Hello, world!");
              }
            });

            // Somewhere else in your code
            await myTask.trigger({ message: "Hello, world!" }, {
              idempotencyKey: "unique-key-123",
              concurrencyKey: "user123-task",
              queue: {
                name: "my-task-queue",
                concurrencyLimit: 5
              },
            });
        - lang: curl
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/tasks/my-task/trigger" \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer tr_dev_1234" \
              -d '{
                    "payload": {
                      "message": "Hello, world!"
                    },
                    "context": {
                      "user": "user123"
                    },
                    "options": {
                      "queue": {
                        "name": "default",
                        "concurrencyLimit": 5
                      },
                      "concurrencyKey": "user123-task",
                      "idempotencyKey": "unique-key-123"
                    }
                  }'
        - lang: python
          source: |-
            import requests

            url = "https://api.trigger.dev/api/v1/tasks/my-task/trigger"
            headers = {
                "Content-Type": "application/json",
                "Authorization": "Bearer tr_dev_1234"
            }
            data = {
                "payload": {
                    "message": "Hello, world!"
                },
                "context": {
                    "user": "user123"
                },
                "options": {
                    "queue": {
                        "name": "default",
                        "concurrencyLimit": 5
                    },
                    "concurrencyKey": "user123-task",
                    "idempotencyKey": "unique-key-123"
                }
            }

            response = requests.post(url, headers=headers, json=data)
            print(response.json())

  "/api/v1/tasks/{taskIdentifier}/batch":
    parameters:
      - $ref: "#/components/parameters/taskIdentifier"
    post:
      operationId: batch_trigger_task_by_id_v1
      summary: Batch trigger a specific task
      description: Batch trigger a specific task with up to 1,000 payloads. All items in the batch run the same task.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: ["items"]
              properties:
                items:
                  type: array
                  description: An array of payloads to trigger the task with (max 1,000 items).
                  maxItems: 1000
                  items:
                    $ref: "#/components/schemas/TriggerTaskRequestBody"
      responses:
        "200":
          description: Batch triggered successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchTriggerTaskResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Task not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - tasks
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { task } from "@trigger.dev/sdk";

            export const myTask = task({
              id: "my-task",
              run: async (payload: { message: string }) => {
                console.log("Hello, world!");
              }
            });

            // Somewhere else in your code
            await myTask.batchTrigger([
              { payload: { message: "Hello, world!" } },
              { payload: { message: "Hello again!" } },
            ]);
        - lang: curl
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/tasks/my-task/batch" \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer tr_dev_1234" \
              -d '{
                    "items": [
                      { "payload": { "message": "Hello, world!" } },
                      { "payload": { "message": "Hello again!" } }
                    ]
                  }'

  "/api/v1/tasks/batch":
    post:
      operationId: batch_trigger_task_v1
      summary: Batch trigger tasks
      description: Batch trigger tasks with up to 1,000 payloads with SDK 4.3.1+ (500 in prior versions).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/BatchTriggerV2RequestBody"
      responses:
        "200":
          description: Task batch triggered successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BatchTriggerTaskResponse"
        "400":
          description: Invalid request parameters or body
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
      tags:
        - tasks
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { task } from "@trigger.dev/sdk";

            export const myTask = await task({
              id: "my-task",
              run: async (payload: { message: string }) => {
                console.log("Hello, world!");
              }
            });

            // Somewhere else in your code
            await myTask.batchTrigger([
              {
                payload: { message: "Hello, world!" },
                options: {
                  idempotencyKey: "unique-key-123",
                  concurrencyKey: "user-123-task",
                  queue: {
                    name: "my-task-queue",
                    concurrencyLimit: 5
                  }
                }
              }
            ]);
        - lang: curl
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/tasks/batch" \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer tr_dev_1234" \
              -d '{
                    "items": [
                      {
                        "task": "my-task",
                        "payload": {
                          "message": "Hello, world!"
                        },
                        "context": {
                          "user": "user123"
                        },
                        "options": {
                          "queue": {
                            "name": "default",
                            "concurrencyLimit": 5
                          },
                          "concurrencyKey": "user123-task",
                          "idempotencyKey": "unique-key-123"
                        }
                      }
                    ]
                  }'

  "/api/v1/batches/{batchId}":
    parameters:
      - $ref: "#/components/parameters/batchId"
    get:
      operationId: retrieve_batch_v1
      summary: Retrieve a batch
      description: Retrieve a batch by its ID, including its status and the IDs of all runs in the batch.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The batch ID.
                  status:
                    type: string
                    enum: [PENDING, PROCESSING, COMPLETED, PARTIAL_FAILED, ABORTED]
                    description: The current status of the batch.
                  idempotencyKey:
                    type: string
                    nullable: true
                    description: The idempotency key provided when triggering, if any.
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                  runCount:
                    type: integer
                    description: The total number of runs in the batch.
                  runs:
                    type: array
                    items:
                      type: string
                    description: Array of run IDs in the batch.
                  successfulRunCount:
                    type: integer
                    nullable: true
                    description: Number of successful runs (populated after completion).
                  failedRunCount:
                    type: integer
                    nullable: true
                    description: Number of failed runs (populated after completion).
                  errors:
                    type: array
                    nullable: true
                    description: Error details for failed items (present for PARTIAL_FAILED batches).
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: The index of the failed item.
                        taskIdentifier:
                          type: string
                          description: The task identifier of the failed item.
                        error:
                          type: object
                          description: The error details.
                        errorCode:
                          type: string
                          nullable: true
                          description: An optional error code.
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - batches
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: Fetch
          source: |-
            const response = await fetch("https://api.trigger.dev/api/v1/batches/batch_1234", {
              headers: {
                "Authorization": `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
              },
            });
            const batch = await response.json();

  "/api/v1/batches/{batchId}/results":
    parameters:
      - $ref: "#/components/parameters/batchId"
    get:
      operationId: get_batch_results_v1
      summary: Retrieve batch results
      description: Returns the execution results of all completed runs in a batch. Only finished runs (successful or failed) are included in the items array — runs that are still executing are omitted. Returns 404 if the batch doesn't exist.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The batch ID.
                  items:
                    type: array
                    description: Execution results for each run in the batch.
                    items:
                      type: object
                      required: [ok, id]
                      properties:
                        ok:
                          type: boolean
                          description: Whether this run completed successfully.
                        id:
                          type: string
                          description: The run ID.
                        output:
                          type: string
                          description: The serialized output as a string (present when ok is true). Use outputType to determine how to parse it — for "application/json" use JSON.parse().
                        outputType:
                          type: string
                          description: The content type of the serialized output, e.g. "application/json".
                        error:
                          type: object
                          description: Error details (present when ok is false).
                        usage:
                          type: object
                          properties:
                            durationMs:
                              type: number
                              description: Duration of the run in milliseconds.
                        taskIdentifier:
                          type: string
                          description: The task identifier.
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      tags:
        - batches
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: Fetch
          source: |-
            const response = await fetch("https://api.trigger.dev/api/v1/batches/batch_1234/results", {
              headers: {
                "Authorization": `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
              },
            });
            const results = await response.json();

  "/api/v1/queues":
    get:
      operationId: list_queues_v1
      summary: List all queues
      description: List all queues in your environment with pagination support.
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          required: false
          description: Page number of the queue listing (1-based)
        - in: query
          name: perPage
          schema:
            type: integer
          required: false
          description: Number of queues per page
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListQueuesResult"
        "401":
          description: Unauthorized request
      tags:
        - queues
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { queues } from "@trigger.dev/sdk";

            // List all queues
            const allQueues = await queues.list();

            // With pagination
            const pagedQueues = await queues.list({
              page: 1,
              perPage: 20,
            });

  "/api/v1/queues/{queueParam}":
    get:
      operationId: retrieve_queue_v1
      summary: Retrieve a queue
      description: Get a queue by its ID, or by type and name.
      parameters:
        - in: path
          name: queueParam
          required: true
          schema:
            type: string
          description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` query parameter.
          example: queue_1234
        - in: query
          name: type
          schema:
            type: string
            enum: [id, task, custom]
            default: id
          required: false
          description: |
            How to interpret the `queueParam` path parameter:
            - `id`: Treat as a queue ID (default)
            - `task`: Treat as a task ID to get the task's default queue
            - `custom`: Treat as a custom queue name
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/QueueObject"
        "401":
          description: Unauthorized request
        "404":
          description: Queue not found
      tags:
        - queues
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { queues } from "@trigger.dev/sdk";

            // Using queue ID
            const queue = await queues.retrieve("queue_1234");

            // Using type and name for a task queue
            const taskQueue = await queues.retrieve({
              type: "task",
              name: "my-task-id",
            });

            // Using type and name for a custom queue
            const customQueue = await queues.retrieve({
              type: "custom",
              name: "my-custom-queue",
            });

  "/api/v1/queues/{queueParam}/pause":
    post:
      operationId: pause_queue_v1
      summary: Pause or resume a queue
      description: Pause a queue to prevent new runs from starting, or resume a paused queue. Runs that are currently executing will continue to completion.
      parameters:
        - in: path
          name: queueParam
          required: true
          schema:
            type: string
          description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
          example: queue_1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: ["action"]
              properties:
                type:
                  type: string
                  enum: [id, task, custom]
                  default: id
                  description: |
                    How to interpret the `queueParam` path parameter:
                    - `id`: Treat as a queue ID (default)
                    - `task`: Treat as a task ID to get the task's default queue
                    - `custom`: Treat as a custom queue name
                action:
                  type: string
                  enum: [pause, resume]
                  description: Whether to pause or resume the queue
      responses:
        "200":
          description: Queue paused or resumed successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/QueueObject"
        "400":
          description: Invalid request parameters
        "401":
          description: Unauthorized request
        "404":
          description: Queue not found
      tags:
        - queues
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { queues } from "@trigger.dev/sdk";

            // Pause a queue
            await queues.pause("queue_1234");
            await queues.pause({ type: "task", name: "my-task-id" });

            // Resume a queue
            await queues.resume("queue_1234");
            await queues.resume({ type: "task", name: "my-task-id" });

  "/api/v1/queues/{queueParam}/concurrency/override":
    post:
      operationId: override_queue_concurrency_v1
      summary: Override queue concurrency limit
      description: Override the concurrency limit of a queue. This is useful for temporarily scaling up or down based on demand.
      parameters:
        - in: path
          name: queueParam
          required: true
          schema:
            type: string
          description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
          example: queue_1234
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: ["concurrencyLimit"]
              properties:
                type:
                  type: string
                  enum: [id, task, custom]
                  default: id
                  description: |
                    How to interpret the `queueParam` path parameter:
                    - `id`: Treat as a queue ID (default)
                    - `task`: Treat as a task ID to get the task's default queue
                    - `custom`: Treat as a custom queue name
                concurrencyLimit:
                  type: integer
                  minimum: 0
                  maximum: 100000
                  description: The new concurrency limit to set for the queue
      responses:
        "200":
          description: Concurrency limit overridden successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/QueueObject"
        "400":
          description: Invalid request parameters
        "401":
          description: Unauthorized request
        "404":
          description: Queue not found
      tags:
        - queues
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { queues } from "@trigger.dev/sdk";

            // Override concurrency limit to 5
            await queues.overrideConcurrencyLimit("queue_1234", 5);

            // Using type and name
            await queues.overrideConcurrencyLimit(
              { type: "task", name: "my-task-id" },
              20
            );

  "/api/v1/queues/{queueParam}/concurrency/reset":
    post:
      operationId: reset_queue_concurrency_v1
      summary: Reset queue concurrency limit
      description: Reset the concurrency limit of a queue back to its base value defined in code.
      parameters:
        - in: path
          name: queueParam
          required: true
          schema:
            type: string
          description: The queue ID (e.g., `queue_1234`), or the name of the queue when using the `type` body parameter.
          example: queue_1234
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [id, task, custom]
                  default: id
                  description: |
                    How to interpret the `queueParam` path parameter:
                    - `id`: Treat as a queue ID (default)
                    - `task`: Treat as a task ID to get the task's default queue
                    - `custom`: Treat as a custom queue name
      responses:
        "200":
          description: Concurrency limit reset successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/QueueObject"
        "400":
          description: Queue is not overridden or invalid request parameters
        "401":
          description: Unauthorized request
        "404":
          description: Queue not found
      tags:
        - queues
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { queues } from "@trigger.dev/sdk";

            // Reset concurrency limit to the base value
            await queues.resetConcurrencyLimit("queue_1234");

            // Using type and name
            await queues.resetConcurrencyLimit({
              type: "task",
              name: "my-task-id",
            });

  "/api/v1/waitpoints/tokens":
    post:
      operationId: create_waitpoint_token_v1
      summary: Create a waitpoint token
      description: >-
        Creates a new waitpoint token that can be used to pause a run until an external event completes it.
        The token includes a `url` which can be called via HTTP POST to complete the waitpoint.
        Use the token ID with `wait.forToken()` inside a task to pause execution until the token is completed.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateWaitpointTokenRequest"
      responses:
        "200":
          description: Waitpoint token created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateWaitpointTokenResponse"
        "401":
          description: Unauthorized
        "422":
          description: Unprocessable Entity
        "500":
          description: Internal Server Error
      tags:
        - waitpoints
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { wait } from "@trigger.dev/sdk";

            const token = await wait.createToken({
              timeout: "1h",
              tags: ["user:1234567"],
            });

            console.log(token.id);  // e.g. "waitpoint_abc123"
            console.log(token.url); // HTTP callback URL to complete externally

    get:
      operationId: list_waitpoint_tokens_v1
      summary: List waitpoint tokens
      description: >-
        Returns a paginated list of waitpoint tokens for the current environment.
        Results are ordered by creation date, newest first. Use cursor-based pagination
        with `page[after]` and `page[before]` to navigate pages.
      parameters:
        - in: query
          name: "page[size]"
          schema:
            type: integer
            minimum: 1
            maximum: 100
          required: false
          description: Number of tokens to return per page (1–100).
        - in: query
          name: "page[after]"
          schema:
            type: string
          required: false
          description: Return tokens after this cursor (from `pagination.next` in a previous response).
        - in: query
          name: "page[before]"
          schema:
            type: string
          required: false
          description: Return tokens before this cursor (from `pagination.previous` in a previous response).
        - in: query
          name: "filter[status]"
          schema:
            type: string
          required: false
          description: >-
            Comma-separated list of statuses to filter by.
            Allowed values: `WAITING`, `COMPLETED`, `TIMED_OUT`.
          example: "WAITING,COMPLETED"
        - in: query
          name: "filter[idempotencyKey]"
          schema:
            type: string
          required: false
          description: Filter by idempotency key.
        - in: query
          name: "filter[tags]"
          schema:
            type: string
          required: false
          description: Comma-separated list of tags to filter by.
          example: "user:1234567,org:9876543"
        - in: query
          name: "filter[createdAt][period]"
          schema:
            type: string
          required: false
          description: >-
            Shorthand time period to filter by creation date (e.g. `1h`, `24h`, `7d`).
            Cannot be combined with `filter[createdAt][from]` or `filter[createdAt][to]`.
          example: "24h"
        - in: query
          name: "filter[createdAt][from]"
          schema:
            type: string
            format: date-time
          required: false
          description: Filter tokens created at or after this ISO 8601 timestamp.
        - in: query
          name: "filter[createdAt][to]"
          schema:
            type: string
            format: date-time
          required: false
          description: Filter tokens created at or before this ISO 8601 timestamp.
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListWaitpointTokensResult"
        "401":
          description: Unauthorized
        "422":
          description: Invalid query parameters (e.g. unrecognised status value)
        "500":
          description: Internal Server Error
      tags:
        - waitpoints
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { wait } from "@trigger.dev/sdk";

            // Iterate over all tokens (auto-paginated)
            for await (const token of wait.listTokens()) {
              console.log(token.id, token.status);
            }

            // Filter by status and tags
            for await (const token of wait.listTokens({
              status: ["WAITING"],
              tags: ["user:1234567"],
            })) {
              console.log(token.id);
            }

  "/api/v1/waitpoints/tokens/{waitpointId}/callback/{callbackHash}":
    post:
      operationId: complete_waitpoint_token_callback_v1
      summary: Complete a waitpoint token via HTTP callback
      description: >-
        Completes a waitpoint token using the pre-signed callback URL returned in the `url`
        field when the token was created. No API key is required — the `callbackHash` in
        the URL acts as the authentication token.


        This is designed to be given directly to external services (e.g. as a webhook URL)
        so they can unblock a waiting run without needing access to your API key.
        The entire request body is passed as the output data to the waiting run.


        If the token is already completed, this is a no-op and returns `success: true`.
      parameters:
        - in: path
          name: waitpointId
          required: true
          schema:
            type: string
          description: The ID of the waitpoint token.
          example: waitpoint_abc123
        - in: path
          name: callbackHash
          required: true
          schema:
            type: string
          description: >-
            The HMAC hash that authenticates the request. This is embedded in the `url`
            returned when creating the token — do not construct it manually.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: >-
                Any JSON object. The entire body is passed as the output data to the run
                waiting on this token. If the body is not valid JSON, an empty object is used.
              example:
                status: approved
                comment: Looks good to me!
      responses:
        "200":
          description: Waitpoint token completed successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CompleteWaitpointTokenResponse"
        "401":
          description: Invalid callback URL or hash mismatch
        "404":
          description: Waitpoint token not found
        "405":
          description: Method not allowed
        "411":
          description: Content-Length header is required
        "413":
          description: Request body too large
        "500":
          description: Internal Server Error
      tags:
        - waitpoints
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |-
            # The full URL is returned as `url` when you create a token
            curl -X POST "https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash" \
              -H "Content-Type: application/json" \
              -d '{"status": "approved", "comment": "Looks good to me!"}'
        - lang: typescript
          source: |-
            import { wait } from "@trigger.dev/sdk";

            // In your task: create the token and send the URL to an external service
            const token = await wait.createToken({ timeout: "1h" });

            await sendApprovalRequestEmail({
              callbackUrl: token.url, // give this URL to the external service
            });

            // The external service POSTs to token.url to unblock the run
            const result = await wait.forToken<{ status: string }>(token);

  "/api/v1/waitpoints/tokens/{waitpointId}/complete":
    post:
      operationId: complete_waitpoint_token_v1
      summary: Complete a waitpoint token
      description: >-
        Completes a waitpoint token, unblocking any run that is waiting for it via `wait.forToken()`.
        An optional `data` payload can be passed and will be returned to the waiting run.
        If the token is already completed, this is a no-op and returns `success: true`.


        This endpoint accepts both secret API keys and short-lived JWTs (public access tokens),
        making it safe to call from frontend clients.
      parameters:
        - in: path
          name: waitpointId
          required: true
          schema:
            type: string
          description: The ID of the waitpoint token to complete.
          example: waitpoint_abc123
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CompleteWaitpointTokenRequest"
      responses:
        "200":
          description: Waitpoint token completed successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CompleteWaitpointTokenResponse"
        "401":
          description: Unauthorized
        "404":
          description: Waitpoint token not found
        "500":
          description: Internal Server Error
      tags:
        - waitpoints
      security:
        - secretKey: []
        - publicAccessToken: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { wait } from "@trigger.dev/sdk";

            // Complete with data (returned to the waiting run)
            await wait.completeToken(token, {
              status: "approved",
              comment: "Looks good to me!",
            });

            // Complete with no data
            await wait.completeToken(token, {});

  "/api/v1/waitpoints/tokens/{waitpointId}":
    get:
      operationId: retrieve_waitpoint_token_v1
      summary: Retrieve a waitpoint token
      description: >-
        Retrieves a waitpoint token by its ID, including its current status and output
        if it has been completed.
      parameters:
        - in: path
          name: waitpointId
          required: true
          schema:
            type: string
          description: The ID of the waitpoint token.
          example: waitpoint_abc123
      responses:
        "200":
          description: Successful request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WaitpointTokenObject"
        "401":
          description: Unauthorized
        "404":
          description: Waitpoint token not found
        "500":
          description: Internal Server Error
      tags:
        - waitpoints
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          source: |-
            import { wait } from "@trigger.dev/sdk";

            const token = await wait.retrieveToken("waitpoint_abc123");

            console.log(token.status); // "WAITING" | "COMPLETED" | "TIMED_OUT"

            if (token.status === "COMPLETED") {
              console.log(token.output);
            }

components:
  parameters:
    taskIdentifier:
      in: path
      name: taskIdentifier
      required: true
      schema:
        type: string
      description: The id of a task
      example: my-task
    runsFilterWithEnv:
      in: query
      name: filter
      style: deepObject
      explode: true
      description: |
        Use this parameter to filter the runs. You can filter by created at, environment, status, task identifier, and version.

        For array fields, you can provide multiple values to filter by using a comma-separated list. For example, to get QUEUED and EXECUTING runs, you can use `filter[status]=QUEUED,EXECUTING`.

        For object fields, you should use the "form" encoding style. For example, to filter by the period, you can use `filter[createdAt][period]=1d`.
      schema:
        allOf:
          - $ref: "#/components/schemas/CommonRunsFilter"
          - $ref: "#/components/schemas/EnvFilter"
    runsFilter:
      in: query
      name: filter
      style: deepObject
      explode: true
      description: |
        Use this parameter to filter the runs. You can filter by created at, status, task identifier, and version.

        For array fields, you can provide multiple values to filter by using a comma-separated list. For example, to get QUEUED and EXECUTING runs, you can use `filter[status]=QUEUED,EXECUTING`.

        For object fields, you should use the "form" encoding style. For example, to filter by the period, you can use `filter[createdAt][period]=1d`.
      schema:
        $ref: "#/components/schemas/CommonRunsFilter"
    cursorPagination:
      in: query
      name: page
      style: deepObject
      explode: true
      description: |
        Use this parameter to paginate the results. You can specify the number of runs per page, and the ID of the run to start the page after or before.

        For object fields like `page`, you should use the "form" encoding style. For example, to get the next page of runs, you can use `page[after]=run_1234`.
      schema:
        type: object
        properties:
          size:
            type: integer
            maximum: 100
            minimum: 10
            default: 25
            description: Number of runs per page. Maximum is 100.
          after:
            type: string
            description: The ID of the run to start the page after. This will set the direction of the pagination to forward.
          before:
            type: string
            description: The ID of the run to start the page before. This will set the direction of the pagination to backward.
    runId:
      in: path
      name: runId
      required: true
      schema:
        type: string
      description: |
        The ID of an run, starts with `run_`. The run ID will be returned when you trigger a run on a task.
      example: run_1234
    batchId:
      in: path
      name: batchId
      required: true
      schema:
        type: string
      description: The ID of the batch, starts with `batch_`.
      example: batch_1234
    projectRef:
      in: path
      name: projectRef
      required: true
      schema:
        type: string
      description: The external ref of the project. You can find this in the project settings. Starts with `proj_`.
      example: proj_yubjwjsfkxnylobaqvqz
    env:
      in: path
      name: env
      required: true
      schema:
        type: string
        enum: [dev, staging, prod]
      description: The environment of the project to list variables for.
      example: dev
    envvarName:
      in: path
      name: name
      required: true
      schema:
        type: string
      description: The name of the environment variable.
      example: SLACK_API_KEY
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: |
        Use your project-specific Secret API key. Will start with `tr_dev_`, `tr_prod`, `tr_stg`, etc.

        You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard.

        Our TypeScript SDK will default to using the value of the `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function.

        ```typescript
        import { configure } from "@trigger.dev/sdk";

        configure({ accessToken: "tr_dev_1234" });
        ```

    personalAccessToken:
      type: http
      scheme: bearer
      description: |
        Use your user-specific Personal Access Token, which you can generate from the Trigger.dev dashboard in your account settings. (It will start with `tr_pat_`.)

        Our TypeScript SDK will default to using the value of the `TRIGGER_ACCESS_TOKEN` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function.

        ```typescript
        import { configure } from "@trigger.dev/sdk";

        configure({ accessToken: "tr_pat_1234" });
        ```

    publicAccessToken:
      type: http
      scheme: bearer
      description: |
        A short-lived JWT scoped to a specific waitpoint token. Returned as `publicAccessToken`
        when you call `wait.createToken()` or `POST /api/v1/waitpoints/tokens`.

        This token is safe to embed in frontend clients — it can only complete the specific
        waitpoint it was issued for and cannot be used for any other API operations.

  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:
        id:
          type: string
          description: The ID of the run that was triggered.
          example: run_1234
    QueueOptions:
      type: object
      properties:
        name:
          type: string
          description: You can define a shared queue and then pass the name in to your task.
        concurrencyLimit:
          type: integer
          minimum: 0
          maximum: 1000
          description: An optional property that specifies the maximum number of concurrent run executions. If this property is omitted, the task can potentially use up the full concurrency of an environment.
    QueueObject:
      type: object
      required: ["id", "name", "type", "running", "queued", "paused"]
      properties:
        id:
          type: string
          description: The queue ID, e.g., `queue_1234`
          example: queue_1234
        name:
          type: string
          description: The queue name. For task queues, this is the task ID. For custom queues, this is the name you specified.
          example: my-task-id
        type:
          type: string
          enum: [task, custom]
          description: |
            The type of queue:
            - `task`: Created automatically for each task
            - `custom`: Created explicitly in your code using `queue()`
          example: task
        running:
          type: integer
          description: The number of runs currently executing
          example: 5
        queued:
          type: integer
          description: The number of runs currently queued
          example: 10
        paused:
          type: boolean
          description: Whether the queue is paused. When paused, no new runs will start.
          example: false
        concurrencyLimit:
          type: integer
          nullable: true
          description: The current concurrency limit of the queue
          example: 10
        concurrency:
          type: object
          description: Detailed concurrency information
          properties:
            current:
              type: integer
              nullable: true
              description: The effective/current concurrency limit
              example: 10
            base:
              type: integer
              nullable: true
              description: The base concurrency limit defined in code
              example: 10
            override:
              type: integer
              nullable: true
              description: The override concurrency limit (if set)
              example: null
            overriddenAt:
              type: string
              format: date-time
              nullable: true
              description: When the concurrency limit was overridden
              example: null
            overriddenBy:
              type: string
              nullable: true
              description: Who overrode the concurrency limit (null if via API)
              example: null
    ListQueuesResult:
      type: object
      required: ["data", "pagination"]
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/QueueObject"
          description: An array of queue objects
        pagination:
          type: object
          properties:
            currentPage:
              type: integer
              description: The current page number
              example: 1
            totalPages:
              type: integer
              description: The total number of pages
              example: 5
            count:
              type: integer
              description: The total number of queues
              example: 50
    BatchTriggerRequestBody:
      type: object
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/TriggerTaskRequestBody"
          description: An array of payloads to trigger the task with
      required: ["items"]
    BatchTriggerV2RequestBody:
      type: object
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/BatchTriggerTaskRequestBodyItem"
          description: An array of payloads to trigger the task with
      required: ["items"]
    BatchTriggerTaskResponse:
      type: object
      required: ["batchId", "runs"]
      properties:
        batchId:
          type: string
          description: The ID of the batch that was triggered
          example: batch_1234
        runs:
          type: array
          items:
            type: string
          description: An array of run IDs that were triggered
    BatchTriggerTaskRequestBodyItem:
      type: object
      allOf:
        - $ref: "#/components/schemas/TriggerTaskRequestBody"
        - type: object
          properties:
            task:
              type: string
              description: The task identifier to trigger. This is the `id` set in your `task()` functions.
          required:
            - task
    TriggerTaskRequestBody:
      type: object
      properties:
        payload:
          description: The payload can include any valid JSON
        context:
          description: The context can include any valid JSON
        options:
          type: object
          properties:
            queue:
              $ref: "#/components/schemas/QueueOptions"
            concurrencyKey:
              type: string
              description: Scope the concurrency limit to a specific key.
            idempotencyKey:
              type: string
              description: An optional property that specifies the idempotency key used to prevent creating duplicate runs. If you provide an existing idempotency key, we will return the existing run ID.
            ttl:
              $ref: "#/components/schemas/TTL"
            delay:
              $ref: "#/components/schemas/Delay"
            tags:
              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 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.
            machine:
              type: string
              enum:
                - micro
                - small-1x
                - small-2x
                - medium-1x
                - medium-2x
                - large-1x
                - large-2x
              example: "small-2x"
              description: The machine preset to use for this run. This will override the task's machine preset and any defaults.
    TTL:
      type:
        - string
        - number
      description: "The time-to-live for this run. If the run is not executed within this time, it will be removed from the queue and never execute. You can use a string in this format: `1h`, `1m`, `1h42m` or a number of seconds (min. 1)."
      example: "1h42m"
    Delay:
      type: string
      description: |
        The delay before the task is executed. This can be a Date object, a string like `1h` or a date-time string.

        * "1h" - 1 hour
        * "30d" - 30 days
        * "15m" - 15 minutes
        * "2w" - 2 weeks
        * "60s" - 60 seconds
        * new Date("2025-01-01T00:00:00Z")
    EnvFilter:
      type: object
      properties:
        env:
          type: array
          items:
            type: string
            description: The environment of the project
            enum:
              - dev
              - staging
              - prod
    CommonRunsFilter:
      type: object
      properties:
        createdAt:
          type: object
          properties:
            from:
              type: string
              format: date-time
              description: The start date to filter the runs by
            to:
              type: string
              format: date-time
              description: The end date to filter the runs by
            period:
              type: string
              description: The period to filter the runs by
              example: 1d
        status:
          type: array
          items:
            type: string
            description: The status of the run
            enum:
              - PENDING_VERSION
              - QUEUED
              - EXECUTING
              - REATTEMPTING
              - FROZEN
              - COMPLETED
              - CANCELED
              - FAILED
              - CRASHED
              - INTERRUPTED
              - SYSTEM_FAILURE
        taskIdentifier:
          type: array
          items:
            type: string
          description: The identifier of the task that was run
        version:
          type: array
          items:
            type: string
          description: The version of the worker that executed the run
        bulkAction:
          type: string
          description: The bulk action ID to filter the runs by
          example: bulk_1234
        schedule:
          type: string
          description: The schedule ID to filter the runs by
          example: schedule_1234
        isTest:
          type: boolean
          description: Whether the run is a test run or not
          example: false
        tag:
          type: array
          items:
            type: string
          description: The tags that are attached to the run
    ListRunsResult:
      type: object
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/ListRunItem"
        pagination:
          type: object
          properties:
            next:
              type: string
              description: The run ID to start the next page after. This should be used as the `page[after]` parameter in the next request.
              example: run_1234
            previous:
              type: string
              description: The run ID to start the previous page before. This should be used as the `page[before]` parameter in the next request.
              example: run_5678
    ListRunItem:
      type: object
      required:
        - id
        - status
        - taskIdentifier
        - createdAt
        - updatedAt
        - isTest
        - env
      properties:
        id:
          type: string
          description: The unique ID of the run, prefixed with `run_`
          example: run_1234
        status:
          type: string
          description: The status of the run
          enum:
            - PENDING_VERSION
            - QUEUED
            - EXECUTING
            - REATTEMPTING
            - FROZEN
            - COMPLETED
            - CANCELED
            - FAILED
            - CRASHED
            - INTERRUPTED
            - SYSTEM_FAILURE
        taskIdentifier:
          type: string
          description: The identifier of the task that was run
          example: my-task
        version:
          type: string
          example: 20240523.1
          description: The version of the worker that executed the run
        env:
          type: object
          description: The environment of the run
          required:
            - id
            - name
          properties:
            id:
              type: string
              description: The unique ID of the environment
              example: cl1234
            name:
              type: string
              description: The name of the environment
              example: dev
            user:
              type: string
              description: If this is a dev environment, the username of the user represented by this environment
              example: Anna
        idempotencyKey:
          type: string
          description: The idempotency key used to prevent creating duplicate runs, if provided
          example: idempotency_key_1234
        isTest:
          type: boolean
          description: Whether the run is a test run or not
          example: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
          description: The time the run started
        finishedAt:
          type: string
          format: date-time
          description: The time the run finished
        delayedUntil:
          type: string
          format: date-time
          description: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
        ttl:
          $ref: "#/components/schemas/TTL"
        expiredAt:
          type: string
          format: date-time
          description: If the run had a TTL and that time has passed, when the run "expired".
        tags:
          type: array
          description: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
          example: ["user_5df987al13", "org_c6b7dycmxw"]
          items:
            type: string
            description: A tag must be between 1 and 128 characters, a run can have up to 10 tags attached to it.
        costInCents:
          type: number
          example: 0.00292
          description: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
        baseCostInCents:
          type: number
          example: 0.0025
          description: The invocation cost of the run in cents. This cost does not apply to DEV runs.
        durationMs:
          type: number
          example: 491
          description: The duration of compute (so far) in milliseconds. This does not include waits.

    InvalidEnvVarsRequestResponse:
      type: object
      properties:
        error:
          type: string
        issues:
          type: array
          items:
            type: object
        variableErrors:
          type: array
          items:
            type: object
    SucceedResponse:
      type: object
      properties:
        success:
          type: boolean
      required: ["success"]
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Something went wrong
      required: ["error"]
    ErrorWithDetailsResponse:
      type: object
      properties:
        error:
          type: string
          example: Query Error
        details:
          type: array
          items:
            type: object
            required:
              - code
              - message
            properties:
              code:
                type: string
                description: The error code
                example: custom
              message:
                type: string
                description: The error message
                example: "Invalid status values: FOOBAR"
              path:
                type: array
                items:
                  type: string
                description: The relevant path in the request
                example: ["filter[status]"]
      required: ["error"]
    ListEnvironmentVariablesResponse:
      type: array
      items:
        "$ref": "#/components/schemas/EnvVar"
    EnvVarValue:
      type: object
      properties:
        value:
          type: string
          example: slack_123456
      required: ["value"]
    EnvVar:
      type: object
      properties:
        name:
          type: string
          example: SLACK_API_KEY
        value:
          type: string
          example: slack_123456
      required: ["name", "value"]
    RescheduleRunRequestBody:
      type: object
      properties:
        delay:
          oneOf:
            - type: string
              description: The duration to delay the run by. The duration should be in the format of `1d`, `6h`, `10m`, `11s`, etc.
              example: 1hr
            - type: string
              format: date-time
              description: The Date to delay the run until, e.g. `new Date()` or `"2024-06-25T15:45:26Z"`
              example: 2024-06-25T15:45:26Z
    CommonRunObject:
      type: object
      required:
        - id
        - status
        - taskIdentifier
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: The unique ID of the run, prefixed with `run_`
          example: run_1234
        status:
          type: string
          description: The status of the run
          enum:
            - PENDING_VERSION
            - DELAYED
            - QUEUED
            - EXECUTING
            - REATTEMPTING
            - FROZEN
            - COMPLETED
            - CANCELED
            - FAILED
            - CRASHED
            - INTERRUPTED
            - SYSTEM_FAILURE
        taskIdentifier:
          type: string
          description: The identifier of the task that was run
          example: my-task
        version:
          type: string
          example: 20240523.1
          description: The version of the worker that executed the run
        idempotencyKey:
          type: string
          description: The idempotency key used to prevent creating duplicate runs, if provided
          example: idempotency_key_1234
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isTest:
          type: boolean
          description: Whether the run is a test run or not
          example: false
        startedAt:
          type: string
          format: date-time
          description: The time the run started
        finishedAt:
          type: string
          format: date-time
          description: The time the run finished
        delayedUntil:
          type: string
          format: date-time
          description: If the run was triggered with a delay, this will be the time the run will be enqueued to execute
        ttl:
          $ref: "#/components/schemas/TTL"
        expiredAt:
          type: string
          format: date-time
          description: If the run had a TTL and that time has passed, when the run "expired".
        tags:
          type: array
          description: Tags can be attached to a run to make it easy to find runs (in the dashboard or using SDK functions like `runs.list`)
          example: ["user_5df987al13", "org_c6b7dycmxw"]
          items:
            type: string
            description: A tag must be between 1 and 128 characters, a run can have up to 10 tags attached to it.
        metadata:
          type: object
          description: The metadata of the run. See [Metadata](/runs/metadata) for more information.
          example: { "foo": "bar" }
        costInCents:
          type: number
          example: 0.00292
          description: The compute cost of the run (so far) in cents. This cost does not apply to DEV runs.
        baseCostInCents:
          type: number
          example: 0.0025
          description: The invocation cost of the run in cents. This cost does not apply to DEV runs.
        durationMs:
          type: number
          example: 491
          description: The duration of compute (so far) in milliseconds. This does not include waits.
        depth:
          type: integer
          example: 0
          description: The depth of the run in the task run hierarchy. The root run has a depth of 0.
        batchId:
          type: string
          description: The ID of the batch that this run belongs to
          example: batch_1234
        triggerFunction:
          type: string
          description: The name of the function that triggered the run
          enum:
            - trigger
            - triggerAndWait
            - batchTrigger
            - batchTriggerAndWait

    RetrieveRunResponse:
      allOf:
        - $ref: "#/components/schemas/CommonRunObject"
        - type: object
          required:
            - attempts
          properties:
            payload:
              type: object
              description: The payload that was sent to the task. Will be omitted if the request was made with a Public API key
              example: { "foo": "bar" }
            payloadPresignedUrl:
              type: string
              description: The presigned URL to download the payload. Will only be included if the payload is too large to be included in the response. Expires in 5 minutes.
              example: "https://r2.cloudflarestorage.com/packets/yubjwjsfkxnylobaqvqz/dev/run_p4omhh45hgxxnq1re6ovy/payload.json?X-Amz-Expires=300&X-Amz-Date=20240625T154526Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=10b064e58a0680db5b5e077be2be3b2a%2F20240625%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=88604cb993ffc151b4d73f2439da431d9928488e4b3dcfa4a7c8f1819"
            output:
              type: object
              description: The output of the run. Will be omitted if the request was made with a Public API key
              example: { "foo": "bar" }
            outputPresignedUrl:
              type: string
              description: The presigned URL to download the output. Will only be included if the output is too large to be included in the response. Expires in 5 minutes.
              example: "https://r2.cloudflarestorage.com/packets/yubjwjsfkxnylobaqvqz/dev/run_p4omhh45hgxxnq1re6ovy/payload.json?X-Amz-Expires=300&X-Amz-Date=20240625T154526Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=10b064e58a0680db5b5e077be2be3b2a%2F20240625%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=88604cb993ffc151b4d73f2439da431d9928488e4b3dcfa4a7c8f1819"
            relatedRuns:
              type: object
              properties:
                root:
                  $ref: "#/components/schemas/CommonRunObject"
                  description: The root run of the run hierarchy. Will be omitted if the run is the root run
                parent:
                  $ref: "#/components/schemas/CommonRunObject"
                  description: The parent run of the run. Will be omitted if the run is the root run
                children:
                  description: The immediate children of the run. Will be omitted if the run has no children
                  type: array
                  items:
                    $ref: "#/components/schemas/CommonRunObject"
            schedule:
              type: object
              description: The schedule that triggered the run. Will be omitted if the run was not triggered by a schedule
              required:
                - id
                - generator
              properties:
                id:
                  type: string
                  description: The unique ID of the schedule, prefixed with `sched_`
                  example: sched_1234
                externalId:
                  type: string
                  description: The external ID of the schedule. Can be anything that is useful to you (e.g., user ID, org ID, etc.)
                  example: user_1234
                deduplicationKey:
                  type: string
                  description: The deduplication key used to prevent creating duplicate schedules
                  example: dedup_key_1234
                generator:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - CRON
                    expression:
                      type: string
                      description: The cron expression used to generate the schedule
                      example: 0 0 * * *
                    description:
                      type: string
                      description: The description of the generator in plain english
                      example: Every day at midnight
            attempts:
              type: array
              items:
                type: object
                required:
                  - id
                  - status
                  - createdAt
                  - updatedAt
                properties:
                  id:
                    type: string
                    description: The unique ID of the attempt, prefixed with `attempt_`
                    example: attempt_1234
                  status:
                    type: string
                    enum:
                      - PENDING
                      - EXECUTING
                      - PAUSED
                      - COMPLETED
                      - FAILED
                      - CANCELED
                  error:
                    $ref: "#/components/schemas/SerializedError"
                  createdAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
                  startedAt:
                    type: string
                    format: date-time
                  completedAt:
                    type: string
                    format: date-time
    CreateScheduleOptions:
      type: object
      properties:
        task:
          type: string
        cron:
          type: string
        deduplicationKey:
          type: string
        externalId:
          type: string
        timezone:
          type: string
          example: "America/New_York"
          description: Defaults to "UTC". In IANA format ("America/New_York"). If set then it will trigger at the CRON frequency in that timezone and respect daylight savings time.
      required:
        - task
        - cron
        - deduplicationKey
    UpdateScheduleOptions:
      type: object
      properties:
        task:
          type: string
        cron:
          type: string
        externalId:
          type: string
        timezone:
          type: string
          example: "America/New_York"
          description: Defaults to "UTC". In IANA format ("America/New_York"). If set then it will trigger at the CRON frequency in that timezone and respect daylight savings time.
      required:
        - task
        - cron
    ScheduleObject:
      type: object
      properties:
        id:
          type: string
          example: sched_1234
          description: The unique ID of the schedule, prefixed with 'sched_'
        task:
          type: string
          example: my-scheduled-task
          description: The id of the scheduled task that will be triggered by this
            schedule
        "type":
          type: string
          example: IMPERATIVE
          description: The type of schedule, `DECLARATIVE` or `IMPERATIVE`. Declarative schedules are declared in your code by setting the `cron` property on a `schedules.task`. Imperative schedules are created in the dashboard or by using the imperative SDK functions like `schedules.create()`.
        active:
          type: boolean
          example: true
          description: Whether the schedule is active or not
        deduplicationKey:
          type: string
          example: dedup_key_1234
          description: The deduplication key used to prevent creating duplicate schedules
        externalId:
          type: string
          example: user_1234
          description: The external ID of the schedule. Can be anything that is useful
            to you (e.g., user ID, org ID, etc.)
        generator:
          type: object
          properties:
            type:
              type: string
              enum:
                - CRON
            expression:
              type: string
              description: The cron expression used to generate the schedule
              example: 0 0 * * *
            description:
              type: string
              description: The description of the generator in plain english
              example: Every day at midnight
        timezone:
          type: string
          example: "America/New_York"
          description: Defaults to UTC. In IANA format, if set then it will trigger at the CRON frequency in that timezone and respect daylight savings time.
        nextRun:
          type: string
          format: date-time
          description: The next time the schedule will run
          example: "2024-04-01T00:00:00Z"
        environments:
          type: array
          items:
            "$ref": "#/components/schemas/ScheduleEnvironment"
    ListSchedulesResult:
      type: object
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/ScheduleObject"
        pagination:
          type: object
          properties:
            currentPage:
              type: integer
            totalPages:
              type: integer
            count:
              type: integer
    GetTimezonesResult:
      type: object
      properties:
        timezones:
          type: array
          items:
            type: string
          example:
            [
              "UTC",
              "Africa/Abidjan",
              "Africa/Accra",
              "Africa/Addis_Ababa",
              "Africa/Algiers",
              "Africa/Asmera",
              "Africa/Bamako",
              "Africa/Bangui",
              "Africa/Banjul",
              "Africa/Bissau",
              "Africa/Blantyre",
              "Africa/Brazzaville",
              "Africa/Bujumbura",
              "Africa/Cairo",
              "Africa/Casablanca",
              "Africa/Ceuta",
              "Africa/Conakry",
              "Africa/Dakar",
              "Africa/Dar_es_Salaam",
              "Africa/Djibouti",
              "Africa/Douala",
              "Africa/El_Aaiun",
              "Africa/Freetown",
              "Africa/Gaborone",
              "Africa/Harare",
              "Africa/Johannesburg",
              "Africa/Juba",
              "Africa/Kampala",
              "Africa/Khartoum",
              "Africa/Kigali",
              "Africa/Kinshasa",
              "Africa/Lagos",
              "Africa/Libreville",
              "Africa/Lome",
              "Africa/Luanda",
              "Africa/Lubumbashi",
              "Africa/Lusaka",
              "Africa/Malabo",
              "Africa/Maputo",
              "Africa/Maseru",
              "Africa/Mbabane",
              "Africa/Mogadishu",
              "Africa/Monrovia",
              "Africa/Nairobi",
              "Africa/Ndjamena",
              "Africa/Niamey",
              "Africa/Nouakchott",
              "Africa/Ouagadougou",
              "Africa/Porto-Novo",
              "Africa/Sao_Tome",
              "Africa/Tripoli",
              "Africa/Tunis",
              "Africa/Windhoek",
              "America/Adak",
              "America/Anchorage",
              "America/Anguilla",
              "America/Antigua",
              "America/Araguaina",
              "America/Argentina/La_Rioja",
              "America/Argentina/Rio_Gallegos",
              "America/Argentina/Salta",
              "America/Argentina/San_Juan",
              "America/Argentina/San_Luis",
              "America/Argentina/Tucuman",
              "America/Argentina/Ushuaia",
              "America/Aruba",
              "America/Asuncion",
              "America/Bahia",
              "America/Bahia_Banderas",
              "America/Barbados",
              "America/Belem",
              "America/Belize",
              "America/Blanc-Sablon",
              "America/Boa_Vista",
              "America/Bogota",
              "America/Boise",
              "America/Buenos_Aires",
              "America/Cambridge_Bay",
              "America/Campo_Grande",
              "America/Cancun",
              "America/Caracas",
              "America/Catamarca",
              "America/Cayenne",
              "America/Cayman",
              "America/Chicago",
              "America/Chihuahua",
              "America/Ciudad_Juarez",
              "America/Coral_Harbour",
              "America/Cordoba",
              "America/Costa_Rica",
              "America/Creston",
              "America/Cuiaba",
              "America/Curacao",
              "America/Danmarkshavn",
              "America/Dawson",
              "America/Dawson_Creek",
              "America/Denver",
              "America/Detroit",
              "America/Dominica",
              "America/Edmonton",
              "America/Eirunepe",
              "America/El_Salvador",
              "America/Fort_Nelson",
              "America/Fortaleza",
              "America/Glace_Bay",
              "America/Godthab",
              "America/Goose_Bay",
              "America/Grand_Turk",
              "America/Grenada",
              "America/Guadeloupe",
              "America/Guatemala",
              "America/Guayaquil",
              "America/Guyana",
              "America/Halifax",
              "America/Havana",
              "America/Hermosillo",
              "America/Indiana/Knox",
              "America/Indiana/Marengo",
              "America/Indiana/Petersburg",
              "America/Indiana/Tell_City",
              "America/Indiana/Vevay",
              "America/Indiana/Vincennes",
              "America/Indiana/Winamac",
              "America/Indianapolis",
              "America/Inuvik",
              "America/Iqaluit",
              "America/Jamaica",
              "America/Jujuy",
              "America/Juneau",
              "America/Kentucky/Monticello",
              "America/Kralendijk",
              "America/La_Paz",
              "America/Lima",
              "America/Los_Angeles",
              "America/Louisville",
              "America/Lower_Princes",
              "America/Maceio",
              "America/Managua",
              "America/Manaus",
              "America/Marigot",
              "America/Martinique",
              "America/Matamoros",
              "America/Mazatlan",
              "America/Mendoza",
              "America/Menominee",
              "America/Merida",
              "America/Metlakatla",
              "America/Mexico_City",
              "America/Miquelon",
              "America/Moncton",
              "America/Monterrey",
              "America/Montevideo",
              "America/Montserrat",
              "America/Nassau",
              "America/New_York",
              "America/Nipigon",
              "America/Nome",
              "America/Noronha",
              "America/North_Dakota/Beulah",
              "America/North_Dakota/Center",
              "America/North_Dakota/New_Salem",
              "America/Ojinaga",
              "America/Panama",
              "America/Pangnirtung",
              "America/Paramaribo",
              "America/Phoenix",
              "America/Port-au-Prince",
              "America/Port_of_Spain",
              "America/Porto_Velho",
              "America/Puerto_Rico",
              "America/Punta_Arenas",
              "America/Rainy_River",
              "America/Rankin_Inlet",
              "America/Recife",
              "America/Regina",
              "America/Resolute",
              "America/Rio_Branco",
              "America/Santa_Isabel",
              "America/Santarem",
              "America/Santiago",
              "America/Santo_Domingo",
              "America/Sao_Paulo",
              "America/Scoresbysund",
              "America/Sitka",
              "America/St_Barthelemy",
              "America/St_Johns",
              "America/St_Kitts",
              "America/St_Lucia",
              "America/St_Thomas",
              "America/St_Vincent",
              "America/Swift_Current",
              "America/Tegucigalpa",
              "America/Thule",
              "America/Thunder_Bay",
              "America/Tijuana",
              "America/Toronto",
              "America/Tortola",
              "America/Vancouver",
              "America/Whitehorse",
              "America/Winnipeg",
              "America/Yakutat",
              "America/Yellowknife",
              "Antarctica/Casey",
              "Antarctica/Davis",
              "Antarctica/DumontDUrville",
              "Antarctica/Macquarie",
              "Antarctica/Mawson",
              "Antarctica/McMurdo",
              "Antarctica/Palmer",
              "Antarctica/Rothera",
              "Antarctica/Syowa",
              "Antarctica/Troll",
              "Antarctica/Vostok",
              "Arctic/Longyearbyen",
              "Asia/Aden",
              "Asia/Almaty",
              "Asia/Amman",
              "Asia/Anadyr",
              "Asia/Aqtau",
              "Asia/Aqtobe",
              "Asia/Ashgabat",
              "Asia/Atyrau",
              "Asia/Baghdad",
              "Asia/Bahrain",
              "Asia/Baku",
              "Asia/Bangkok",
              "Asia/Barnaul",
              "Asia/Beirut",
              "Asia/Bishkek",
              "Asia/Brunei",
              "Asia/Calcutta",
              "Asia/Chita",
              "Asia/Choibalsan",
              "Asia/Colombo",
              "Asia/Damascus",
              "Asia/Dhaka",
              "Asia/Dili",
              "Asia/Dubai",
              "Asia/Dushanbe",
              "Asia/Famagusta",
              "Asia/Gaza",
              "Asia/Hebron",
              "Asia/Hong_Kong",
              "Asia/Hovd",
              "Asia/Irkutsk",
              "Asia/Jakarta",
              "Asia/Jayapura",
              "Asia/Jerusalem",
              "Asia/Kabul",
              "Asia/Kamchatka",
              "Asia/Karachi",
              "Asia/Katmandu",
              "Asia/Khandyga",
              "Asia/Krasnoyarsk",
              "Asia/Kuala_Lumpur",
              "Asia/Kuching",
              "Asia/Kuwait",
              "Asia/Macau",
              "Asia/Magadan",
              "Asia/Makassar",
              "Asia/Manila",
              "Asia/Muscat",
              "Asia/Nicosia",
              "Asia/Novokuznetsk",
              "Asia/Novosibirsk",
              "Asia/Omsk",
              "Asia/Oral",
              "Asia/Phnom_Penh",
              "Asia/Pontianak",
              "Asia/Pyongyang",
              "Asia/Qatar",
              "Asia/Qostanay",
              "Asia/Qyzylorda",
              "Asia/Rangoon",
              "Asia/Riyadh",
              "Asia/Saigon",
              "Asia/Sakhalin",
              "Asia/Samarkand",
              "Asia/Seoul",
              "Asia/Shanghai",
              "Asia/Singapore",
              "Asia/Srednekolymsk",
              "Asia/Taipei",
              "Asia/Tashkent",
              "Asia/Tbilisi",
              "Asia/Tehran",
              "Asia/Thimphu",
              "Asia/Tokyo",
              "Asia/Tomsk",
              "Asia/Ulaanbaatar",
              "Asia/Urumqi",
              "Asia/Ust-Nera",
              "Asia/Vientiane",
              "Asia/Vladivostok",
              "Asia/Yakutsk",
              "Asia/Yekaterinburg",
              "Asia/Yerevan",
              "Atlantic/Azores",
              "Atlantic/Bermuda",
              "Atlantic/Canary",
              "Atlantic/Cape_Verde",
              "Atlantic/Faeroe",
              "Atlantic/Madeira",
              "Atlantic/Reykjavik",
              "Atlantic/South_Georgia",
              "Atlantic/St_Helena",
              "Atlantic/Stanley",
              "Australia/Adelaide",
              "Australia/Brisbane",
              "Australia/Broken_Hill",
              "Australia/Currie",
              "Australia/Darwin",
              "Australia/Eucla",
              "Australia/Hobart",
              "Australia/Lindeman",
              "Australia/Lord_Howe",
              "Australia/Melbourne",
              "Australia/Perth",
              "Australia/Sydney",
              "Europe/Amsterdam",
              "Europe/Andorra",
              "Europe/Astrakhan",
              "Europe/Athens",
              "Europe/Belgrade",
              "Europe/Berlin",
              "Europe/Bratislava",
              "Europe/Brussels",
              "Europe/Bucharest",
              "Europe/Budapest",
              "Europe/Busingen",
              "Europe/Chisinau",
              "Europe/Copenhagen",
              "Europe/Dublin",
              "Europe/Gibraltar",
              "Europe/Guernsey",
              "Europe/Helsinki",
              "Europe/Isle_of_Man",
              "Europe/Istanbul",
              "Europe/Jersey",
              "Europe/Kaliningrad",
              "Europe/Kiev",
              "Europe/Kirov",
              "Europe/Lisbon",
              "Europe/Ljubljana",
              "Europe/London",
              "Europe/Luxembourg",
              "Europe/Madrid",
              "Europe/Malta",
              "Europe/Mariehamn",
              "Europe/Minsk",
              "Europe/Monaco",
              "Europe/Moscow",
              "Europe/Oslo",
              "Europe/Paris",
              "Europe/Podgorica",
              "Europe/Prague",
              "Europe/Riga",
              "Europe/Rome",
              "Europe/Samara",
              "Europe/San_Marino",
              "Europe/Sarajevo",
              "Europe/Saratov",
              "Europe/Simferopol",
              "Europe/Skopje",
              "Europe/Sofia",
              "Europe/Stockholm",
              "Europe/Tallinn",
              "Europe/Tirane",
              "Europe/Ulyanovsk",
              "Europe/Uzhgorod",
              "Europe/Vaduz",
              "Europe/Vatican",
              "Europe/Vienna",
              "Europe/Vilnius",
              "Europe/Volgograd",
              "Europe/Warsaw",
              "Europe/Zagreb",
              "Europe/Zaporozhye",
              "Europe/Zurich",
              "Indian/Antananarivo",
              "Indian/Chagos",
              "Indian/Christmas",
              "Indian/Cocos",
              "Indian/Comoro",
              "Indian/Kerguelen",
              "Indian/Mahe",
              "Indian/Maldives",
              "Indian/Mauritius",
              "Indian/Mayotte",
              "Indian/Reunion",
              "Pacific/Apia",
              "Pacific/Auckland",
              "Pacific/Bougainville",
              "Pacific/Chatham",
              "Pacific/Easter",
              "Pacific/Efate",
              "Pacific/Enderbury",
              "Pacific/Fakaofo",
              "Pacific/Fiji",
              "Pacific/Funafuti",
              "Pacific/Galapagos",
              "Pacific/Gambier",
              "Pacific/Guadalcanal",
              "Pacific/Guam",
              "Pacific/Honolulu",
              "Pacific/Johnston",
              "Pacific/Kiritimati",
              "Pacific/Kosrae",
              "Pacific/Kwajalein",
              "Pacific/Majuro",
              "Pacific/Marquesas",
              "Pacific/Midway",
              "Pacific/Nauru",
              "Pacific/Niue",
              "Pacific/Norfolk",
              "Pacific/Noumea",
              "Pacific/Pago_Pago",
              "Pacific/Palau",
              "Pacific/Pitcairn",
              "Pacific/Ponape",
              "Pacific/Port_Moresby",
              "Pacific/Rarotonga",
              "Pacific/Saipan",
              "Pacific/Tahiti",
              "Pacific/Tarawa",
              "Pacific/Tongatapu",
              "Pacific/Truk",
              "Pacific/Wake",
              "Pacific/Wallis",
            ]
    ScheduleEnvironment:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        userName:
          type: string
    SerializedError:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Something went wrong
        name:
          type: string
          example: Error
        stackTrace:
          type: string
          example: "Error: Something went wrong"
    ExecuteQueryRequestBody:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The TRQL query to execute
          example: "SELECT run_id, status, triggered_at FROM runs WHERE status = 'Failed' LIMIT 10"
        scope:
          type: string
          enum: ["environment", "project", "organization"]
          default: "environment"
          description: The scope of data to query - environment (default), project, or organization
        period:
          type: string
          nullable: true
          description: Time period shorthand (e.g., "7d", "30d", "1h"). Cannot be used with from/to.
          example: "7d"
        from:
          type: string
          format: date-time
          nullable: true
          description: Start of time range as ISO 8601 timestamp. Must be used with 'to'.
          example: "2024-01-01T00:00:00Z"
        to:
          type: string
          format: date-time
          nullable: true
          description: End of time range as ISO 8601 timestamp. Must be used with 'from'.
          example: "2024-01-31T23:59:59Z"
        format:
          type: string
          enum: ["json", "csv"]
          default: "json"
          description: Response format - "json" returns structured data (default), "csv" returns CSV string
    ExecuteQueryResponse:
      oneOf:
        - type: object
          description: JSON format response
          properties:
            format:
              type: string
              enum: ["json"]
            results:
              type: array
              items:
                type: object
              description: Array of result rows
        - type: object
          description: CSV format response
          properties:
            format:
              type: string
              enum: ["csv"]
            results:
              type: string
              description: CSV-formatted results
    CompleteWaitpointTokenRequest:
      type: object
      properties:
        data:
          description: >-
            Any JSON-serializable value to pass back to the run waiting on this token.
            The data will be returned from `wait.forToken()` as the result payload.
          example:
            status: approved
            comment: Looks good to me!
    CompleteWaitpointTokenResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          enum:
            - true
          description: Always `true` when the request succeeds.
    ListWaitpointTokensResult:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/WaitpointTokenObject"
          description: An array of waitpoint token objects.
        pagination:
          type: object
          properties:
            next:
              type: string
              nullable: true
              description: >-
                Cursor for the next page. Pass as `page[after]` in the next request.
              example: waitpoint_abc123
            previous:
              type: string
              nullable: true
              description: >-
                Cursor for the previous page. Pass as `page[before]` in the next request.
              example: waitpoint_xyz789
    WaitpointTokenObject:
      type: object
      required:
        - id
        - url
        - status
        - tags
        - createdAt
      properties:
        id:
          type: string
          description: The unique ID of the waitpoint token.
          example: waitpoint_abc123
        url:
          type: string
          description: >-
            An HTTP callback URL. A POST request to this URL (with an optional JSON body)
            will complete the waitpoint without needing an API key.
          example: https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash
        status:
          type: string
          enum:
            - WAITING
            - COMPLETED
            - TIMED_OUT
          description: The current status of the waitpoint token.
        idempotencyKey:
          type: string
          nullable: true
          description: The idempotency key used when creating the token, if any.
        idempotencyKeyExpiresAt:
          type: string
          format: date-time
          nullable: true
          description: When the idempotency key expires.
        timeoutAt:
          type: string
          format: date-time
          nullable: true
          description: When the token will time out, if a timeout was set.
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: When the token was completed, if it has been completed.
        output:
          type: string
          nullable: true
          description: >-
            The serialized output data passed when completing the token.
            Only present when `status` is `COMPLETED`.
        outputType:
          type: string
          nullable: true
          description: The content type of the output (e.g. `"application/json"`).
        outputIsError:
          type: boolean
          nullable: true
          description: Whether the output represents an error (e.g. a timeout).
        tags:
          type: array
          items:
            type: string
          description: Tags attached to the waitpoint.
        createdAt:
          type: string
          format: date-time
          description: When the waitpoint token was created.
    CreateWaitpointTokenRequest:
      type: object
      properties:
        idempotencyKey:
          type: string
          description: >-
            An optional idempotency key. If you pass the same key twice before it expires,
            you will receive the original token back. The returned token may already be completed,
            in which case `wait.forToken()` will continue immediately.
          example: approval-user-1234567
        idempotencyKeyTTL:
          type: string
          description: >-
            How long the idempotency key is valid, after which passing the same key
            creates a new waitpoint. Accepts durations like "30s", "1m", "2h", "3d".
          example: 1h
        timeout:
          type: string
          description: >-
            How long to wait before the token times out. When a run is waiting for a timed-out
            token, `wait.forToken()` returns with `ok: false`. Accepts an ISO 8601 date string
            or duration shorthand like "30s", "1m", "2h", "3d", "4w".
          example: 1h
        tags:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Tags to attach to the waitpoint. You can set up to 10 tags, each under 128 characters.
            We recommend namespacing tags with a prefix like `user:1234567` or `org_9876543`.
          example:
            - "user:1234567"
            - "org:9876543"
    CreateWaitpointTokenResponse:
      type: object
      required:
        - id
        - isCached
        - url
      properties:
        id:
          type: string
          description: The unique ID of the waitpoint token.
          example: waitpoint_abc123
        isCached:
          type: boolean
          description: >-
            `true` if an existing token was returned because the same `idempotencyKey`
            was used within its TTL window.
        url:
          type: string
          description: >-
            An HTTP callback URL. A POST request to this URL (with an optional JSON body)
            will complete the waitpoint without needing an API key.
          example: https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash