Sessions API

Create session

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.

POST

api

sessions

Start a session

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

curl --request POST \
  --url https://api.trigger.dev/api/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "externalId": "chat_1234",
  "tags": [
    "<string>"
  ],
  "metadata": {},
  "expiresAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.trigger.dev/api/v1/sessions"

payload = {
    "type": "chat.agent",
    "taskIdentifier": "my-chat",
    "triggerConfig": {
        "basePayload": {},
        "machine": "small-1x",
        "queue": "<string>",
        "tags": ["<string>"],
        "maxAttempts": 5,
        "maxDuration": 2,
        "lockToVersion": "20240523.1",
        "region": "<string>",
        "idleTimeoutInSeconds": 1800
    },
    "externalId": "chat_1234",
    "tags": ["<string>"],
    "metadata": {},
    "expiresAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'chat.agent',
    taskIdentifier: 'my-chat',
    triggerConfig: {
      basePayload: {},
      machine: 'small-1x',
      queue: '<string>',
      tags: ['<string>'],
      maxAttempts: 5,
      maxDuration: 2,
      lockToVersion: '20240523.1',
      region: '<string>',
      idleTimeoutInSeconds: 1800
    },
    externalId: 'chat_1234',
    tags: ['<string>'],
    metadata: {},
    expiresAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.trigger.dev/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'chat.agent',
    'taskIdentifier' => 'my-chat',
    'triggerConfig' => [
        'basePayload' => [
                
        ],
        'machine' => 'small-1x',
        'queue' => '<string>',
        'tags' => [
                '<string>'
        ],
        'maxAttempts' => 5,
        'maxDuration' => 2,
        'lockToVersion' => '20240523.1',
        'region' => '<string>',
        'idleTimeoutInSeconds' => 1800
    ],
    'externalId' => 'chat_1234',
    'tags' => [
        '<string>'
    ],
    'metadata' => [
        
    ],
    'expiresAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v1/sessions"

	payload := strings.NewReader("{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v1/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "session_abc123",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "tags": [
    "chat:1234"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "runId": "run_def456",
  "publicAccessToken": "<string>",
  "isCached": true,
  "externalId": "chat_1234",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "currentRunId": "run_def456",
  "metadata": {},
  "closedAt": "2023-11-07T05:31:56Z",
  "closedReason": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "id": "session_abc123",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "tags": [
    "chat:1234"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "runId": "run_def456",
  "publicAccessToken": "<string>",
  "isCached": true,
  "externalId": "chat_1234",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "currentRunId": "run_def456",
  "metadata": {},
  "closedAt": "2023-11-07T05:31:56Z",
  "closedReason": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "error": "Something went wrong"
}

{
  "error": "Query Error",
  "details": [
    {
      "code": "custom",
      "message": "Invalid status values: FOOBAR",
      "path": [
        "filter[status]"
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

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.

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

configure({ accessToken: "tr_dev_1234" });

Body

application/json

Body for POST /api/v1/sessions. The whole body must be 32KB or smaller.

type

string

required

Free-form discriminator for the session, e.g. chat.agent. Not validated against an enum.

Required string length: 1 - 64

Example:

"chat.agent"

taskIdentifier

string

required

The task this session triggers runs against.

Required string length: 1 - 128

Example:

"my-chat"

triggerConfig

object

required

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.

Show child attributes

externalId

string

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.

Required string length: 1 - 256

Example:

"chat_1234"

Response

An open session already existed for this externalId. The existing session is returned with isCached: true.

A session row.

string

required

The session's friendly ID, prefixed with session_.

Example:

"session_abc123"

type

string

required

The session type discriminator.

Example:

"chat.agent"

taskIdentifier

string

required

The task this session triggers runs against.

Example:

"my-chat"

tags

string[]

required

Tags on the session row.

Example:

["chat:1234"]

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

runId

string

required

Friendly ID of the first run triggered alongside the session.

Example:

"run_def456"

publicAccessToken

string

required

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

boolean

required

true if an open session already existed for this externalId (idempotent upsert), false if newly created.

externalId

string | null

Your stable identity for the session, if one was set.

Example:

"chat_1234"

triggerConfig

object

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.

Show child attributes

currentRunId

string | null

Friendly ID of the live run for this session, if any. Prefixed with run_. Omitted on list rows.

Example:

"run_def456"

metadata

object | null

Arbitrary JSON metadata, or null if unset.

closedAt

string<date-time> | null

When the session was closed, or null if open.

closedReason

string | null

The optional reason recorded when the session was closed.

expiresAt

string<date-time> | null

The session's retention deadline, or null if none.

List sessionsList 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.

⌘I

Start a session

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

curl --request POST \
  --url https://api.trigger.dev/api/v1/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "externalId": "chat_1234",
  "tags": [
    "<string>"
  ],
  "metadata": {},
  "expiresAt": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.trigger.dev/api/v1/sessions"

payload = {
    "type": "chat.agent",
    "taskIdentifier": "my-chat",
    "triggerConfig": {
        "basePayload": {},
        "machine": "small-1x",
        "queue": "<string>",
        "tags": ["<string>"],
        "maxAttempts": 5,
        "maxDuration": 2,
        "lockToVersion": "20240523.1",
        "region": "<string>",
        "idleTimeoutInSeconds": 1800
    },
    "externalId": "chat_1234",
    "tags": ["<string>"],
    "metadata": {},
    "expiresAt": "2023-11-07T05:31:56Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'chat.agent',
    taskIdentifier: 'my-chat',
    triggerConfig: {
      basePayload: {},
      machine: 'small-1x',
      queue: '<string>',
      tags: ['<string>'],
      maxAttempts: 5,
      maxDuration: 2,
      lockToVersion: '20240523.1',
      region: '<string>',
      idleTimeoutInSeconds: 1800
    },
    externalId: 'chat_1234',
    tags: ['<string>'],
    metadata: {},
    expiresAt: '2023-11-07T05:31:56Z'
  })
};

fetch('https://api.trigger.dev/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'chat.agent',
    'taskIdentifier' => 'my-chat',
    'triggerConfig' => [
        'basePayload' => [
                
        ],
        'machine' => 'small-1x',
        'queue' => '<string>',
        'tags' => [
                '<string>'
        ],
        'maxAttempts' => 5,
        'maxDuration' => 2,
        'lockToVersion' => '20240523.1',
        'region' => '<string>',
        'idleTimeoutInSeconds' => 1800
    ],
    'externalId' => 'chat_1234',
    'tags' => [
        '<string>'
    ],
    'metadata' => [
        
    ],
    'expiresAt' => '2023-11-07T05:31:56Z'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v1/sessions"

	payload := strings.NewReader("{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v1/sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"chat.agent\",\n  \"taskIdentifier\": \"my-chat\",\n  \"triggerConfig\": {\n    \"basePayload\": {},\n    \"machine\": \"small-1x\",\n    \"queue\": \"<string>\",\n    \"tags\": [\n      \"<string>\"\n    ],\n    \"maxAttempts\": 5,\n    \"maxDuration\": 2,\n    \"lockToVersion\": \"20240523.1\",\n    \"region\": \"<string>\",\n    \"idleTimeoutInSeconds\": 1800\n  },\n  \"externalId\": \"chat_1234\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"expiresAt\": \"2023-11-07T05:31:56Z\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "session_abc123",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "tags": [
    "chat:1234"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "runId": "run_def456",
  "publicAccessToken": "<string>",
  "isCached": true,
  "externalId": "chat_1234",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "currentRunId": "run_def456",
  "metadata": {},
  "closedAt": "2023-11-07T05:31:56Z",
  "closedReason": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "id": "session_abc123",
  "type": "chat.agent",
  "taskIdentifier": "my-chat",
  "tags": [
    "chat:1234"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "runId": "run_def456",
  "publicAccessToken": "<string>",
  "isCached": true,
  "externalId": "chat_1234",
  "triggerConfig": {
    "basePayload": {},
    "machine": "small-1x",
    "queue": "<string>",
    "tags": [
      "<string>"
    ],
    "maxAttempts": 5,
    "maxDuration": 2,
    "lockToVersion": "20240523.1",
    "region": "<string>",
    "idleTimeoutInSeconds": 1800
  },
  "currentRunId": "run_def456",
  "metadata": {},
  "closedAt": "2023-11-07T05:31:56Z",
  "closedReason": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "error": "Something went wrong"
}

{
  "error": "Query Error",
  "details": [
    {
      "code": "custom",
      "message": "Invalid status values: FOOBAR",
      "path": [
        "filter[status]"
      ]
    }
  ]
}

API reference

Tasks API

Batches API

Runs API

Bulk actions API

Errors API

Queues API

Schedules API

Env Vars API

Deployments API

Waitpoints API

Sessions API

Query API

Create session

Authorizations

Body

Response