github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
aa74e68c71d920e445a55e3610aee4bac287c85f
triggerdotdev--trigger.dev/docs/v3-openapi.yaml
T
Katia Bulatova cc752cc375 fix(webapp): fetch run-scoped trace subtrees for large traces (#4024) 
Fixed trace rendering for child and nested runs in large traces.
Dashboard and trace API responses now load the requested run's trace
subtree instead of depending on the run span appearing in the initial
trace slice.
2026-06-30 13:35:31 +02:00

6030 lines
201 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 OTel trace subtree for the requested run — the run's span as `rootSpan`, its ancestor chain, and its descendant spans. For child or nested runs in a large trace, this is scoped to that run rather than the trace-wide root.
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:
allOf:
- $ref: "#/components/schemas/SpanDetailedSummary"
description: The requested run's span, with nested descendant spans as `children`. Not necessarily the trace-wide root span.
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Run not found
- Trace not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/trace", {
headers: {
Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
},
});
const { trace } = await response.json();
"/api/v1/runs/{runId}/events":
parameters:
- $ref: "#/components/parameters/runId"
get:
operationId: get_run_events_v1
summary: Retrieve run events
description: Returns all OTel span events for a run. Useful for debugging and observability.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
type: object
properties:
spanId:
type: string
description: The span ID of the event.
parentId:
type: string
nullable: true
description: The parent span ID, if any.
runId:
type: string
nullable: true
description: The run ID associated with this event.
message:
type: string
description: The event message.
startTime:
type: string
description: The start time of the event as a bigint string (nanoseconds since epoch).
duration:
type: number
description: The duration of the event in nanoseconds.
isError:
type: boolean
description: Whether this event represents an error.
isPartial:
type: boolean
description: Whether this event is partial (still in progress).
isCancelled:
type: boolean
description: Whether this event was cancelled.
level:
type: string
enum: [TRACE, DEBUG, LOG, INFO, WARN, ERROR]
description: The log level of the event.
kind:
type: string
enum: [UNSPECIFIED, INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER, UNRECOGNIZED, LOG]
description: The kind of span event.
attemptNumber:
type: number
nullable: true
description: The attempt number this event belongs to.
taskSlug:
type: string
description: The task identifier.
events:
type: array
description: Span events (e.g. exceptions, cancellations) that occurred during this event.
items:
type: object
properties:
name:
type: string
description: The event name (e.g. "exception", "cancellation", "attempt_failed").
time:
type: string
format: date-time
description: The time the event occurred.
properties:
type: object
description: Event-specific properties.
style:
type: object
description: Display style metadata for the event.
properties:
icon:
type: string
description: Icon identifier for display.
variant:
type: string
description: Visual variant (e.g. "success", "failure").
accessory:
type: object
description: Accessory display element.
properties:
text:
type: string
style:
type: string
enum: [codepath]
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Run not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/events", {
headers: {
Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`,
},
});
const { events } = await response.json();
"/api/v1/runs/{runId}/metadata":
parameters:
- $ref: "#/components/parameters/runId"
put:
operationId: update_run_metadata_v1
summary: Update run metadata
description: Update the metadata of a run.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
description: The new metadata to set on the run.
example: { key: "value" }
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
description: The updated metadata of the run.
"400":
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or missing run ID
- Invalid metadata
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Task Run not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
label: Save metadata
source: |-
import { metadata, task } from "@trigger.dev/sdk";
export const myTask = task({
id: "my-task",
run: async () => {
await metadata.save({ key: "value" });
}
});
"/api/v2/runs/{runId}/cancel":
parameters:
- $ref: "#/components/parameters/runId"
post:
operationId: cancel_run_v1
summary: Cancel a run
description: Cancels an in-progress run. If the run is already completed, this
will have no effect.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The ID of the run that was canceled.
example: run_1234
"400":
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or missing run ID
- Failed to create new run
"401":
description: Unauthorized request
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Invalid or Missing API key
"404":
description: Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- Run not found
tags:
- runs
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
import { runs } from "@trigger.dev/sdk";
await runs.cancel("run_1234");
"/api/v1/deployments":
get:
operationId: list_deployments_v1
summary: List deployments
description: List deployments for the authenticated environment, ordered by most recent first.
parameters:
- in: query
name: "page[after]"
schema:
type: string
description: The deployment ID to start the search from, to get the next page.
- in: query
name: "page[size]"
schema:
type: integer
minimum: 5
maximum: 100
default: 20
description: The number of deployments to return (default 20, min 5, max 100).
- in: query
name: status
schema:
type: string
enum:
[
"PENDING",
"BUILDING",
"DEPLOYING",
"DEPLOYED",
"FAILED",
"CANCELED",
"TIMED_OUT",
]
description: Filter deployments by status.
- in: query
name: period
schema:
type: string
description: Filter deployments created within this period (e.g. 1d, 7d, 3h).
- in: query
name: from
schema:
type: string
description: Filter deployments created on or after this date (ISO 8601).
- in: query
name: to
schema:
type: string
description: Filter deployments created on or before this date (ISO 8601). Only applied when `from` is also provided.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: The deployment ID
createdAt:
type: string
format: date-time
description: When the deployment was created
shortCode:
type: string
description: The short code for the deployment
version:
type: string
description: The deployment version (e.g., "20250228.1")
runtime:
type: string
nullable: true
description: The runtime used (e.g., "node")
runtimeVersion:
type: string
nullable: true
description: The runtime version
status:
type: string
enum:
[
"PENDING",
"BUILDING",
"DEPLOYING",
"DEPLOYED",
"FAILED",
"CANCELED",
"TIMED_OUT",
]
description: The current status of the deployment
deployedAt:
type: string
format: date-time
nullable: true
description: When the deployment was promoted to DEPLOYED
git:
type: object
nullable: true
description: Git metadata associated with the deployment
error:
type: object
nullable: true
description: Error data if the deployment failed
pagination:
type: object
properties:
next:
type: string
description: Cursor for the next page. Pass as `page[after]` to get the next page. Omitted if there are no more results.
"401":
description: Unauthorized - Access token is missing or invalid
tags:
- deployments
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch(
"https://api.trigger.dev/api/v1/deployments",
{
method: "GET",
headers: {
"Authorization": `Bearer ${secretKey}`,
},
}
);
const { data, pagination } = await response.json();
- lang: curl
source: |-
curl -X GET "https://api.trigger.dev/api/v1/deployments" \
-H "Authorization: Bearer tr_dev_1234"
"/api/v1/deployments/{deploymentId}":
parameters:
- in: path
name: deploymentId
required: true
schema:
type: string
description: The deployment ID.
get:
operationId: get_deployment_v1
summary: Get deployment
description: Retrieve information about a specific deployment by its ID.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
status:
type: string
enum:
[
"PENDING",
"INSTALLING",
"BUILDING",
"DEPLOYING",
"DEPLOYED",
"FAILED",
"CANCELED",
"TIMED_OUT",
]
description: The current status of the deployment
contentHash:
type: string
description: Hash of the deployment content
shortCode:
type: string
description: The short code for the deployment
version:
type: string
description: The deployment version (e.g., "20250228.1")
imageReference:
type: string
nullable: true
description: Reference to the deployment image
imagePlatform:
type: string
description: Platform of the deployment image
externalBuildData:
type: object
nullable: true
description: External build data if applicable
errorData:
type: object
nullable: true
description: Error data if the deployment failed
worker:
type: object
nullable: true
description: Worker information if available
properties:
id:
type: string
version:
type: string
tasks:
type: array
items:
type: object
properties:
id:
type: string
slug:
type: string
filePath:
type: string
exportName:
type: string
"401":
description: Unauthorized - Access token is missing or invalid
"404":
description: Deployment not found
tags:
- deployments
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch(
`https://api.trigger.dev/api/v1/deployments/${deploymentId}`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${secretKey}`,
},
}
);
const deployment = await response.json();
- lang: curl
source: |-
curl -X GET "https://api.trigger.dev/api/v1/deployments/deployment_1234" \
-H "Authorization: Bearer tr_dev_1234"
"/api/v1/deployments/latest":
get:
operationId: get_latest_deployment_v1
summary: Get latest deployment
description: Retrieve information about the latest unmanaged deployment for the authenticated project.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
status:
type: string
enum:
[
"PENDING",
"INSTALLING",
"BUILDING",
"DEPLOYING",
"DEPLOYED",
"FAILED",
"CANCELED",
"TIMED_OUT",
]
description: The current status of the deployment
contentHash:
type: string
description: Hash of the deployment content
shortCode:
type: string
description: The short code for the deployment
version:
type: string
description: The deployment version (e.g., "20250228.1")
imageReference:
type: string
nullable: true
description: Reference to the deployment image
errorData:
type: object
nullable: true
description: Error data if the deployment failed
"401":
description: Unauthorized - API key is missing or invalid
"404":
description: No deployment found
tags:
- deployments
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch(
"https://api.trigger.dev/api/v1/deployments/latest",
{
method: "GET",
headers: {
"Authorization": `Bearer ${secretKey}`,
},
}
);
const deployment = await response.json();
- lang: curl
source: |-
curl -X GET "https://api.trigger.dev/api/v1/deployments/latest" \
-H "Authorization: Bearer tr_dev_1234"
"/api/v1/deployments/{version}/promote":
parameters:
- in: path
name: version
required: true
schema:
type: string
description: The deployment version to promote (e.g., "20250228.1").
post:
operationId: promote_deployment_v1
summary: Promote deployment
description: Promote a previously deployed version to be the current version for the environment. This makes the specified version active for new task runs.
responses:
"200":
description: Deployment promoted successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
version:
type: string
description: The deployment version (e.g., "20250228.1")
shortCode:
type: string
description: The short code for the deployment
"400":
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
"401":
description: Unauthorized - API key is missing or invalid
"404":
description: Deployment not found
tags:
- deployments
security:
- secretKey: []
x-codeSamples:
- lang: typescript
source: |-
const response = await fetch(
`https://api.trigger.dev/api/v1/deployments/${version}/promote`,
{
method: "POST",
headers: {
"Authorization": `Bearer ${secretKey}`,
"Content-Type": "application/json",
},
}
);
const result = await response.json();
- lang: curl
source: |-
curl -X POST "https://api.trigger.dev/api/v1/deployments/20250228.1/promote" \
-H "Authorization: Bearer tr_dev_1234" \
-H "Content-Type: application/json"
"/api/v1/query":
post:
operationId: execute_query_v1
summary: Execute a TRQL query
description: Execute a TRQL (Trigger.dev Query Language) query against your run data. TRQL is a SQL-style query language that allows you to analyze runs, calculate metrics, and export data.
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/ExecuteQueryRequestBody"
responses:
"200":
description: Query executed successfully
content:
application/json:
schema:
"$ref": "#/components/schemas/ExecuteQueryResponse"
"400":
description: Invalid query or request parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Error message describing the query error
"401":
description: Unauthorized - API key is missing or invalid
"500":
description: Internal server error during query execution
tags:
- query
security:
- secretKey: []
x-codeSamples:
- lang: typescript
label: SDK - Basic query
source: |-
import { query } from "@trigger.dev/sdk";
// Basic query with defaults (environment scope, json format)
const result = await query.execute(
"SELECT run_id, status FROM runs LIMIT 10"
);
console.log(result.results);
- lang: typescript
label: SDK - Type-safe query
source: |-
import { query, type QueryTable } from "@trigger.dev/sdk";
// Type-safe query using QueryTable
const result = await query.execute<
QueryTable<"runs", "run_id" | "status" | "triggered_at">
>(
"SELECT run_id, status, triggered_at FROM runs LIMIT 10"
);
result.results.forEach(row => {
console.log(row.run_id, row.status); // Fully typed!
});
- lang: typescript
label: SDK - With options
source: |-
import { query } from "@trigger.dev/sdk";
const result = await query.execute(
"SELECT COUNT(*) as count FROM runs WHERE status = 'Failed'",
{
scope: "project", // Query across all environments
period: "7d", // Last 7 days
format: "json"
}
);
- lang: typescript
label: SDK - CSV export
source: |-
import { query } from "@trigger.dev/sdk";
const csvResult = await query.execute(
"SELECT run_id, status, triggered_at FROM runs",
{
format: "csv",
period: "30d"
}
);
// csvResult.results is a CSV string
const lines = csvResult.results.split('\n');
- lang: curl
label: cURL - Basic query
source: |-
curl -X POST "https://api.trigger.dev/api/v1/query" \
-H "Authorization: Bearer tr_dev_1234" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT run_id, status FROM runs LIMIT 10",
"scope": "environment",
"period": "7d",
"format": "json"
}'
- lang: curl
label: cURL - Aggregation query
source: |-
curl -X POST "https://api.trigger.dev/api/v1/query" \
-H "Authorization: Bearer tr_dev_1234" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT task_identifier, count() as runs, countIf(status = '\''Failed'\'') as failures FROM runs GROUP BY task_identifier",
"scope": "environment",
"from": "2024-01-01T00:00:00Z",
"to": "2024-01-31T23:59:59Z",
"format": "json"
}'
"/api/v1/query/schema":
get:
operationId: get_query_schema_v1
summary: Get query schema
description: Get the schema for TRQL queries, including all available tables, their columns, data types, descriptions, and allowed values.
responses:
"200":
description: Schema retrieved successfully
content:
application/json:
schema:
type: object
properties:
tables:
type: array
items:
type: object
properties:
name:
type: string
description: Table name used in TRQL queries
description:
type: string
description: Description of the table
timeColumn:
type: string
description: The primary time column for this table
columns:
type: array
items:
type: object
properties:
name:
type: string
description: Column name
type:
type: string
description: ClickHouse data type
description:
type: string
description: Column description
example:
type: string
description: Example value
allowedValues:
type: array
items:
type: string
description: Allowed values for enum-like columns
coreColumn:
type: boolean
description: Whether this is a core column included in default queries
"401":
description: Unauthorized - API key is missing or invalid
tags:
- query
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl "https://api.trigger.dev/api/v1/query/schema" \
-H "Authorization: Bearer tr_dev_1234"
"/api/v1/query/dashboards":
get:
operationId: list_dashboards_v1
summary: List built-in dashboards
description: List available built-in dashboards with their widgets. Each dashboard contains pre-built TRQL queries for common metrics like run success rates, costs, and LLM usage.
responses:
"200":
description: Dashboards listed successfully
content:
application/json:
schema:
type: object
properties:
dashboards:
type: array
items:
type: object
properties:
key:
type: string
description: Dashboard identifier (e.g. "overview", "llm")
title:
type: string
description: Dashboard display title
widgets:
type: array
items:
type: object
properties:
id:
type: string
description: Widget identifier
title:
type: string
description: Widget display title
query:
type: string
description: The TRQL query this widget executes
type:
type: string
enum: [bignumber, chart, table]
description: Widget display type
"401":
description: Unauthorized - API key is missing or invalid
tags:
- query
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl "https://api.trigger.dev/api/v1/query/dashboards" \
-H "Authorization: Bearer tr_dev_1234"
"/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);
}
"/api/v1/sessions":
post:
operationId: create_session_v1
summary: Create a session
description: >-
Create a Session and trigger its first run in one atomic call. A Session is
the durable identity for a bi-directional stream of records (the `.in` and
`.out` channels) that survives across the runs processing it.
Idempotent on `externalId` within an environment. Calling create again with
an `externalId` that already maps to an open session returns the existing
session with `isCached: true` and `201` becomes `200`. Reusing an
`externalId` whose session is already closed or expired returns `409`.
Authorize with a secret key, or a public token carrying `write:sessions` for
the session you are creating.
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/CreateSessionRequestBody"
responses:
"201":
description: Session created and its first run triggered.
content:
application/json:
schema:
"$ref": "#/components/schemas/CreatedSessionResponseBody"
"200":
description: >-
An open session already existed for this `externalId`. The existing
session is returned with `isCached: true`.
content:
application/json:
schema:
"$ref": "#/components/schemas/CreatedSessionResponseBody"
"401":
description: Unauthorized
"409":
description: >-
An `externalId` was reused, but its session is already closed or expired.
Closed and expired sessions cannot be reopened.
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorResponse"
"422":
description: >-
Validation failed — for example the request body exceeds 32KB, or
`externalId` starts with the reserved `session_` prefix.
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorWithDetailsResponse"
tags:
- sessions
security:
- secretKey: []
- publicAccessToken: []
x-codeSamples:
- lang: typescript
label: Start a session
source: |-
import { sessions } from "@trigger.dev/sdk";
const { id, runId, publicAccessToken, isCached } = await sessions.start({
type: "chat.agent",
externalId: chatId,
taskIdentifier: "my-chat",
triggerConfig: {
basePayload: { chatId },
tags: [`chat:${chatId}`],
},
});
console.log(id); // e.g. "session_abc123"
console.log(runId); // the first run, e.g. "run_def456"
console.log(isCached); // false on a brand-new session
get:
operationId: list_sessions_v1
summary: List sessions
description: >-
List sessions in the current environment, newest first. Filter by type, tags,
task identifier, external id, status, and creation window. Use cursor-based
pagination with `page[after]` and `page[before]` to navigate pages.
List rows omit `triggerConfig`; retrieve a single session to read it.
parameters:
- $ref: "#/components/parameters/sessionsCursorPagination"
- $ref: "#/components/parameters/sessionsFilter"
responses:
"200":
description: Successful request
content:
application/json:
schema:
"$ref": "#/components/schemas/ListSessionsResult"
"400":
description: Invalid query parameters
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorWithDetailsResponse"
"401":
description: Unauthorized request
tags:
- sessions
security:
- secretKey: []
- publicAccessToken: []
x-codeSamples:
- lang: typescript
label: List sessions
source: |-
import { sessions } from "@trigger.dev/sdk";
for await (const session of sessions.list({
type: "chat.agent",
status: "ACTIVE",
limit: 50,
})) {
console.log(session.id, session.externalId, session.createdAt);
}
"/api/v1/sessions/{session}":
parameters:
- $ref: "#/components/parameters/session"
get:
operationId: retrieve_session_v1
summary: Retrieve a session
description: >-
Retrieve a single session by its friendly id (`session_…`) or your
`externalId`. The response includes `triggerConfig` and the friendly
`currentRunId` of the live run, if any.
responses:
"200":
description: Successful request
content:
application/json:
schema:
"$ref": "#/components/schemas/SessionObject"
"401":
description: Unauthorized request
"404":
description: Session not found
tags:
- sessions
security:
- secretKey: []
- publicAccessToken: []
x-codeSamples:
- lang: typescript
label: Retrieve a session
source: |-
import { sessions } from "@trigger.dev/sdk";
const session = await sessions.retrieve(chatId);
console.log(session.currentRunId, session.tags, session.closedAt);
patch:
operationId: update_session_v1
summary: Update a session
description: >-
Update a session's `tags` or `metadata`. Pass `metadata: null` to clear it.
Requires a secret key — a session public token cannot update a session.
`externalId` is read-only after create: it cannot be changed or cleared.
Sending a value different from the current one (including `null` when one is
set) returns `422`; sending the same value is accepted as a no-op.
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/UpdateSessionRequestBody"
responses:
"200":
description: Session updated successfully
content:
application/json:
schema:
"$ref": "#/components/schemas/SessionObject"
"401":
description: Unauthorized request
"404":
description: Session not found
"422":
description: >-
Validation failed — for example an attempt to change `externalId` to a
different value, or a body exceeding 32KB.
content:
application/json:
schema:
"$ref": "#/components/schemas/ErrorWithDetailsResponse"
tags:
- sessions
security:
- secretKey: []
x-codeSamples:
- lang: typescript
label: Update a session
source: |-
import { sessions } from "@trigger.dev/sdk";
const session = await sessions.update(chatId, {
tags: ["priority"],
metadata: { lastSeenBy: "support" },
});
"/api/v1/sessions/{session}/close":
parameters:
- $ref: "#/components/parameters/session"
post:
operationId: close_session_v1
summary: Close a session
description: >-
Close a session. Closing is terminal and idempotent — closing an
already-closed session returns the existing row unchanged. A closed session
cannot be reopened, and reusing its `externalId` on create returns `409`.
Requires a secret key — a session public token cannot close a session.
requestBody:
required: false
content:
application/json:
schema:
"$ref": "#/components/schemas/CloseSessionRequestBody"
responses:
"200":
description: Session closed successfully. Returns the session row.
content:
application/json:
schema:
"$ref": "#/components/schemas/SessionObject"
"401":
description: Unauthorized request
"404":
description: Session not found
tags:
- sessions
security:
- secretKey: []
x-codeSamples:
- lang: typescript
label: Close a session
source: |-
import { sessions } from "@trigger.dev/sdk";
await sessions.close(chatId, { reason: "user signed out" });
"/api/v1/errors":
get:
operationId: list_errors_v1
summary: List errors
description: |
List error groups in a specific environment. Runs that fail are grouped by a fingerprint derived from the error type, message, and stack trace. Filter by task identifier, version, status, search text, and time range.
parameters:
- $ref: "#/components/parameters/errorsCursorPagination"
- $ref: "#/components/parameters/errorsFilter"
responses:
"200":
description: Successful request
content:
application/json:
schema:
$ref: "#/components/schemas/ListErrorsResult"
"400":
description: Invalid query parameters
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorWithDetailsResponse"
"401":
description: Unauthorized request
tags:
- errors
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: List errors
source: |-
curl -X GET "https://api.trigger.dev/api/v1/errors?filter[status]=unresolved" \
-H "Authorization: Bearer $TRIGGER_SECRET_KEY"
"/api/v1/errors/{errorId}":
parameters:
- $ref: "#/components/parameters/errorId"
get:
operationId: retrieve_error_v1
summary: Retrieve an error
description: Retrieve detailed information about a single error group, including its lifecycle state and the worker versions it has affected.
responses:
"200":
description: Successful request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorObject"
"401":
description: Unauthorized request
"404":
description: Error not found
tags:
- errors
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: Retrieve an error
source: |-
curl -X GET "https://api.trigger.dev/api/v1/errors/error_8f3b2a1c9d4e5f60" \
-H "Authorization: Bearer $TRIGGER_SECRET_KEY"
"/api/v1/errors/{errorId}/resolve":
parameters:
- $ref: "#/components/parameters/errorId"
post:
operationId: resolve_error_v1
summary: Resolve an error
description: |
Mark an error group as resolved. Optionally record the worker version that resolved it. Send a JSON body (use `{}` when you have no fields to set).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
resolvedInVersion:
type: string
description: The worker version the error was resolved in.
example: 20240101.1
responses:
"200":
description: Successful request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorObject"
"401":
description: Unauthorized request
"404":
description: Error not found
tags:
- errors
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: Resolve an error
source: |-
curl -X POST "https://api.trigger.dev/api/v1/errors/error_8f3b2a1c9d4e5f60/resolve" \
-H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"resolvedInVersion": "20240101.1"}'
"/api/v1/errors/{errorId}/ignore":
parameters:
- $ref: "#/components/parameters/errorId"
post:
operationId: ignore_error_v1
summary: Ignore an error
description: |
Mark an error group as ignored. Provide a `duration` to ignore it for a fixed window, and/or thresholds that re-surface the error when exceeded. Send a JSON body (use `{}` to ignore indefinitely).
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
duration:
type: integer
description: How long to ignore the error for, in milliseconds.
example: 86400000
occurrenceRate:
type: number
description: Re-surface the error if its occurrence rate exceeds this many occurrences per minute.
totalOccurrences:
type: integer
description: Re-surface the error once it accrues this many new occurrences after being ignored.
reason:
type: string
description: An optional human-readable reason for ignoring the error.
responses:
"200":
description: Successful request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorObject"
"401":
description: Unauthorized request
"404":
description: Error not found
tags:
- errors
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: Ignore an error
source: |-
curl -X POST "https://api.trigger.dev/api/v1/errors/error_8f3b2a1c9d4e5f60/ignore" \
-H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"duration": 86400000, "reason": "Known flaky dependency"}'
"/api/v1/errors/{errorId}/unresolve":
parameters:
- $ref: "#/components/parameters/errorId"
post:
operationId: unresolve_error_v1
summary: Unresolve an error
description: Move a resolved or ignored error group back to unresolved.
responses:
"200":
description: Successful request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorObject"
"401":
description: Unauthorized request
"404":
description: Error not found
tags:
- errors
security:
- secretKey: []
x-codeSamples:
- lang: curl
label: Unresolve an error
source: |-
curl -X POST "https://api.trigger.dev/api/v1/errors/error_8f3b2a1c9d4e5f60/unresolve" \
-H "Authorization: Bearer $TRIGGER_SECRET_KEY"
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.
sessionsCursorPagination:
in: query
name: page
style: deepObject
explode: true
description: |
Paginate the results. Specify the number of sessions per page, and the ID of the session to start the page after or before.
For object fields like `page`, use the "form" encoding style. For example, to get the next page, use `page[after]=session_1234`.
schema:
type: object
properties:
size:
type: integer
maximum: 100
minimum: 1
default: 20
description: Number of sessions per page. Maximum is 100.
after:
type: string
description: The ID of the session to start the page after. Sets the pagination direction to forward.
before:
type: string
description: The ID of the session to start the page before. Sets the pagination direction to backward.
errorId:
in: path
name: errorId
required: true
schema:
type: string
description: The ID of an error group, starts with `error_`.
example: error_8f3b2a1c9d4e5f60
errorsFilter:
in: query
name: filter
style: deepObject
explode: true
description: |
Filter the error groups. Filter by task identifier, version, status, search text, and time range.
For array fields, provide multiple values as a comma-separated list. For example, to get unresolved and ignored errors, use `filter[status]=unresolved,ignored`.
For the time range, use `filter[period]` (e.g. `filter[period]=7d`) or `filter[from]` / `filter[to]` with ISO timestamps.
schema:
$ref: "#/components/schemas/ErrorsFilter"
errorsCursorPagination:
in: query
name: page
style: deepObject
explode: true
description: |
Paginate the results. Specify the number of errors per page, and the ID of the error to start the page after or before.
For object fields like `page`, use the "form" encoding style. For example, to get the next page, use `page[after]=error_1234`.
schema:
type: object
properties:
size:
type: integer
maximum: 100
minimum: 1
default: 25
description: Number of errors per page. Maximum is 100.
after:
type: string
description: The ID of the error to start the page after. Sets the pagination direction to forward.
before:
type: string
description: The ID of the error to start the page before. Sets the pagination direction 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
session:
in: path
name: session
required: true
schema:
type: string
description: >-
The session's friendly ID (`session_…`) or your `externalId`. The server
disambiguates by the `session_` prefix.
example: session_abc123
sessionsFilter:
in: query
name: filter
style: deepObject
explode: true
description: |
Use this parameter to filter the sessions. You can filter by type, tags, task identifier, external id, status, and created at.
For array fields, you can provide multiple values to filter by using a comma-separated list. For example, to get ACTIVE and CLOSED sessions, you can use `filter[status]=ACTIVE,CLOSED`.
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/SessionsFilter"
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 specific resources, returned as `publicAccessToken` from APIs
such as `wait.createToken()` / `POST /api/v1/waitpoints/tokens` and
`sessions.start()` / `POST /api/v1/sessions`, or minted directly with `auth.createPublicToken()`.
This token is safe to embed in frontend clients — it can only act on the resources its
scopes grant (e.g. `read:sessions:{id}`, `write:sessions:{id}`) and cannot be used for any
other API operations. For session tokens see the [session scopes](/management/authentication#session-scopes).
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
error:
type: string
description: An error group ID (starts with `error_`). Lists the runs behind that error group.
example: error_8f3b2a1c9d4e5f60
ErrorsFilter:
type: object
properties:
taskIdentifier:
type: array
items:
type: string
description: The identifier of the task the error belongs to
version:
type: array
items:
type: string
description: The worker version the error occurred in
status:
type: array
items:
type: string
enum:
- unresolved
- resolved
- ignored
description: The lifecycle status of the error group
search:
type: string
description: Free-text search across the error type and message
from:
type: string
format: date-time
description: The start of the time range to count occurrences within
to:
type: string
format: date-time
description: The end of the time range to count occurrences within
period:
type: string
description: A relative time range to count occurrences within
example: 7d
ErrorListItem:
type: object
required:
- id
- fingerprint
- taskIdentifier
- errorType
- errorMessage
- status
- count
- firstSeen
- lastSeen
properties:
id:
type: string
description: The unique ID of the error group, prefixed with `error_`
example: error_8f3b2a1c9d4e5f60
fingerprint:
type: string
description: The raw fingerprint the error is grouped by
taskIdentifier:
type: string
description: The identifier of the task the error belongs to
errorType:
type: string
description: The error type or name (e.g. `TypeError`)
errorMessage:
type: string
description: The normalized error message
status:
type: string
enum:
- unresolved
- resolved
- ignored
count:
type: integer
description: The number of occurrences within the requested time range
firstSeen:
type: string
format: date-time
description: When the error group was first seen (global)
lastSeen:
type: string
format: date-time
description: When the error group was last seen (global)
resolvedAt:
type: string
format: date-time
nullable: true
ignoredUntil:
type: string
format: date-time
nullable: true
ListErrorsResult:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/ErrorListItem"
pagination:
type: object
properties:
next:
type: string
description: The error ID to start the next page after. Pass it as `page[after]`.
example: error_8f3b2a1c9d4e5f60
previous:
type: string
description: The error ID to start the previous page before. Pass it as `page[before]`.
ErrorObject:
type: object
required:
- id
- fingerprint
- taskIdentifier
- errorType
- errorMessage
- status
- count
- firstSeen
- lastSeen
- affectedVersions
properties:
id:
type: string
description: The unique ID of the error group, prefixed with `error_`
example: error_8f3b2a1c9d4e5f60
fingerprint:
type: string
description: The raw fingerprint the error is grouped by
taskIdentifier:
type: string
description: The identifier of the task the error belongs to
errorType:
type: string
description: The error type or name (e.g. `TypeError`)
errorMessage:
type: string
description: The normalized error message
count:
type: integer
description: The total number of occurrences of this error group
firstSeen:
type: string
format: date-time
lastSeen:
type: string
format: date-time
affectedVersions:
type: array
items:
type: string
description: The most recent worker versions the error has occurred in (up to five)
status:
type: string
enum:
- unresolved
- resolved
- ignored
resolvedAt:
type: string
format: date-time
nullable: true
resolvedInVersion:
type: string
nullable: true
resolvedBy:
type: string
nullable: true
description: The ID of the user who resolved the error, when attributable
ignoredAt:
type: string
format: date-time
nullable: true
ignoredUntil:
type: string
format: date-time
nullable: true
ignoredReason:
type: string
nullable: true
ignoredByUserId:
type: string
nullable: true
ignoredUntilOccurrenceRate:
type: number
nullable: true
ignoredUntilTotalOccurrences:
type: integer
nullable: true
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.
SessionTriggerConfig:
type: object
description: >-
Trigger options applied to every run a session schedules. `basePayload` is the
wire payload merged into each run; the remaining fields map onto the standard
trigger options.
required:
- basePayload
properties:
basePayload:
type: object
additionalProperties: true
description: >-
Base payload passed to every run this session triggers. For `chat.agent`
this carries `{ chatId, ...clientData }`.
machine:
type: string
description: Machine preset for each run, e.g. `small-1x`.
example: small-1x
queue:
type: string
maxLength: 128
description: Queue to schedule runs on.
tags:
type: array
maxItems: 5
items:
type: string
maxLength: 128
description: Tags applied to every run this session triggers.
maxAttempts:
type: integer
minimum: 1
maximum: 10
description: Maximum retry attempts per run.
maxDuration:
type: integer
minimum: 1
description: Per-run wall-clock cap in seconds.
lockToVersion:
type: string
description: Pin every run to a specific worker version.
example: "20240523.1"
region:
type: string
description: Region to schedule runs in.
idleTimeoutInSeconds:
type: integer
minimum: 1
maximum: 3600
description: Idle timeout surfaced to `chat.agent` via the wire payload.
CreateSessionRequestBody:
type: object
description: >-
Body for `POST /api/v1/sessions`. The whole body must be 32KB or smaller.
required:
- type
- taskIdentifier
- triggerConfig
properties:
type:
type: string
minLength: 1
maxLength: 64
description: >-
Free-form discriminator for the session, e.g. `chat.agent`. Not validated
against an enum.
example: chat.agent
taskIdentifier:
type: string
minLength: 1
maxLength: 128
description: The task this session triggers runs against.
example: my-chat
triggerConfig:
$ref: "#/components/schemas/SessionTriggerConfig"
externalId:
type: string
minLength: 1
maxLength: 256
description: >-
Your stable identity for the session, unique per environment. Cannot start
with the reserved `session_` prefix. Reusing an `externalId` makes create
idempotent; reusing one whose session is closed or expired returns `409`.
example: chat_1234
tags:
type: array
maxItems: 10
items:
type: string
maxLength: 128
description: Up to 10 tags on the session row, for dashboard filtering.
metadata:
type: object
additionalProperties: true
description: Arbitrary JSON metadata.
expiresAt:
type: string
format: date-time
description: Absolute expiry timestamp for retention.
SessionObject:
type: object
description: A session row.
required:
- id
- type
- taskIdentifier
- tags
- createdAt
- updatedAt
properties:
id:
type: string
description: The session's friendly ID, prefixed with `session_`.
example: session_abc123
externalId:
type: string
nullable: true
description: Your stable identity for the session, if one was set.
example: chat_1234
type:
type: string
description: The session type discriminator.
example: chat.agent
taskIdentifier:
type: string
description: The task this session triggers runs against.
example: my-chat
triggerConfig:
$ref: "#/components/schemas/SessionTriggerConfig"
currentRunId:
type: string
nullable: true
description: >-
Friendly ID of the live run for this session, if any. Prefixed with `run_`.
Omitted on list rows.
example: run_def456
tags:
type: array
items:
type: string
description: Tags on the session row.
example: ["chat:1234"]
metadata:
type: object
additionalProperties: true
nullable: true
description: Arbitrary JSON metadata, or `null` if unset.
closedAt:
type: string
format: date-time
nullable: true
description: When the session was closed, or `null` if open.
closedReason:
type: string
nullable: true
description: The optional reason recorded when the session was closed.
expiresAt:
type: string
format: date-time
nullable: true
description: The session's retention deadline, or `null` if none.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
CreatedSessionResponseBody:
allOf:
- $ref: "#/components/schemas/SessionObject"
- type: object
required:
- runId
- publicAccessToken
- isCached
properties:
runId:
type: string
description: Friendly ID of the first run triggered alongside the session.
example: run_def456
publicAccessToken:
type: string
description: >-
Session-scoped public access token carrying `read:sessions:{key}` and
`write:sessions:{key}`. Default TTL is 1 hour. Safe to pass to frontend
clients.
isCached:
type: boolean
description: >-
`true` if an open session already existed for this `externalId`
(idempotent upsert), `false` if newly created.
UpdateSessionRequestBody:
type: object
description: >-
Body for `PATCH /api/v1/sessions/{session}`. The whole body must be 32KB or
smaller. Every field is optional; omitted fields are left unchanged.
properties:
tags:
type: array
maxItems: 10
items:
type: string
maxLength: 128
description: Replaces the tags on the session row.
metadata:
type: object
additionalProperties: true
nullable: true
description: Replaces the metadata. Pass `null` to clear it.
externalId:
type: string
nullable: true
minLength: 1
maxLength: 256
description: >-
Read-only after create: cannot be changed or cleared. Sending a value
different from the current one (including `null` when one is set) returns
`422`; sending the same value is idempotent.
CloseSessionRequestBody:
type: object
description: Body for `POST /api/v1/sessions/{session}/close`. Up to 1KB.
properties:
reason:
type: string
maxLength: 256
description: Optional reason recorded on the session row.
example: user signed out
SessionsFilter:
type: object
properties:
type:
type: array
items:
type: string
description: The session type(s) to filter by.
example: ["chat.agent"]
tags:
type: array
items:
type: string
description: The tags to filter by.
taskIdentifier:
type: array
items:
type: string
description: The task identifier(s) to filter by.
externalId:
type: string
description: Exact match on your `externalId`.
status:
type: array
items:
type: string
enum:
- ACTIVE
- CLOSED
- EXPIRED
description: The lifecycle status(es) to filter by.
createdAt:
type: object
properties:
from:
type: string
format: date-time
description: The start date to filter the sessions by.
to:
type: string
format: date-time
description: The end date to filter the sessions by.
period:
type: string
description: The period to filter the sessions by.
example: 1d
ListSessionsResult:
type: object
properties:
data:
type: array
items:
"$ref": "#/components/schemas/SessionObject"
pagination:
type: object
properties:
next:
type: string
description: >-
The session ID to start the next page after. Pass it as the
`page[after]` parameter on the next request.
example: session_abc123
previous:
type: string
description: >-
The session ID to start the previous page before. Pass it as the
`page[before]` parameter on the next request.
example: session_xyz789
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
Reference in New Issue View Git Blame Copy Permalink