---
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/{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