JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const agentSchedule = await client.agents.schedules.create('agent_01HXKD2E5NQM3T9AYWCFMGWT9Y', {
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
metadata: { name: 'name' },
spec: { schedule: {} },
});
console.log(agentSchedule.metadata);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
agent_schedule = client.agents.schedules.create(
agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
metadata={
"name": "name"
},
spec={
"schedule": {}
},
)
print(agent_schedule.metadata)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
"go.cadenya.com/cadenya-go/shared"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
agentSchedule, err := client.Agents.Schedules.New(
context.TODO(),
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
cadenya.AgentScheduleNewParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
Metadata: shared.CreateResourceMetadataParam{
Name: "name",
},
Spec: cadenya.AgentScheduleSpecParam{
Schedule: cadenya.AgentScheduleSpecScheduleParam{},
},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", agentSchedule.Metadata)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
agent_schedule = cadenya.agents.schedules.create(
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
metadata: {name: "name"},
spec: {schedule: {}}
)
puts(agent_schedule)cadenya agents:schedules create \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
--metadata '{name: name}' \
--spec '{schedule: {}}'curl --request POST \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"name": "<string>",
"externalId": "<string>",
"labels": {}
},
"spec": {
"schedule": {
"calendars": [
{
"second": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"minute": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"hour": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfMonth": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"month": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfWeek": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"comment": "<string>"
}
],
"intervals": [
{
"every": "<string>",
"offset": "<string>"
}
],
"timezone": "<string>"
},
"firstUserMessage": "<string>",
"variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
"systemPromptData": {},
"firstUserMessageData": {}
}
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules",
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([
'metadata' => [
'name' => '<string>',
'externalId' => '<string>',
'labels' => [
]
],
'spec' => [
'schedule' => [
'calendars' => [
[
'second' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'minute' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'hour' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'dayOfMonth' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'month' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'dayOfWeek' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'comment' => '<string>'
]
],
'intervals' => [
[
'every' => '<string>',
'offset' => '<string>'
]
],
'timezone' => '<string>'
],
'firstUserMessage' => '<string>',
'variationId' => 'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
'systemPromptData' => [
],
'firstUserMessageData' => [
]
]
]),
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;
}HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"name\": \"<string>\",\n \"externalId\": \"<string>\",\n \"labels\": {}\n },\n \"spec\": {\n \"schedule\": {\n \"calendars\": [\n {\n \"second\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"minute\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"hour\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"dayOfMonth\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"month\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"dayOfWeek\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"comment\": \"<string>\"\n }\n ],\n \"intervals\": [\n {\n \"every\": \"<string>\",\n \"offset\": \"<string>\"\n }\n ],\n \"timezone\": \"<string>\"\n },\n \"firstUserMessage\": \"<string>\",\n \"variationId\": \"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP\",\n \"systemPromptData\": {},\n \"firstUserMessageData\": {}\n }\n}")
.asString();{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"schedule": {
"calendars": [
{
"second": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"minute": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"hour": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfMonth": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"month": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfWeek": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"comment": "<string>"
}
],
"intervals": [
{
"every": "<string>",
"offset": "<string>"
}
],
"timezone": "<string>"
},
"firstUserMessage": "<string>",
"variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
"systemPromptData": {},
"firstUserMessageData": {}
},
"info": {
"nextFireAt": "2023-11-07T05:31:56Z",
"lastFireAt": "2023-11-07T05:31:56Z",
"lastObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
"lastSkippedAt": "2023-11-07T05:31:56Z",
"lastSkipReason": "<string>",
"totalFires": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
}
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Agent Schedules
Create a schedule
Fire an objective on a cadence. Calendar rules for wall-clock times, interval rules for fixed durations, and a skip policy so runs never stack.
POST
/
v1
/
workspaces
/
{workspaceId}
/
agents
/
{agentId}
/
schedules
JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const agentSchedule = await client.agents.schedules.create('agent_01HXKD2E5NQM3T9AYWCFMGWT9Y', {
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
metadata: { name: 'name' },
spec: { schedule: {} },
});
console.log(agentSchedule.metadata);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
agent_schedule = client.agents.schedules.create(
agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
metadata={
"name": "name"
},
spec={
"schedule": {}
},
)
print(agent_schedule.metadata)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
"go.cadenya.com/cadenya-go/shared"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
agentSchedule, err := client.Agents.Schedules.New(
context.TODO(),
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
cadenya.AgentScheduleNewParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
Metadata: shared.CreateResourceMetadataParam{
Name: "name",
},
Spec: cadenya.AgentScheduleSpecParam{
Schedule: cadenya.AgentScheduleSpecScheduleParam{},
},
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", agentSchedule.Metadata)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
agent_schedule = cadenya.agents.schedules.create(
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
metadata: {name: "name"},
spec: {schedule: {}}
)
puts(agent_schedule)cadenya agents:schedules create \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
--metadata '{name: name}' \
--spec '{schedule: {}}'curl --request POST \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"metadata": {
"name": "<string>",
"externalId": "<string>",
"labels": {}
},
"spec": {
"schedule": {
"calendars": [
{
"second": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"minute": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"hour": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfMonth": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"month": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfWeek": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"comment": "<string>"
}
],
"intervals": [
{
"every": "<string>",
"offset": "<string>"
}
],
"timezone": "<string>"
},
"firstUserMessage": "<string>",
"variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
"systemPromptData": {},
"firstUserMessageData": {}
}
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules",
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([
'metadata' => [
'name' => '<string>',
'externalId' => '<string>',
'labels' => [
]
],
'spec' => [
'schedule' => [
'calendars' => [
[
'second' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'minute' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'hour' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'dayOfMonth' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'month' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'dayOfWeek' => [
[
'start' => 123,
'end' => 123,
'step' => 123
]
],
'comment' => '<string>'
]
],
'intervals' => [
[
'every' => '<string>',
'offset' => '<string>'
]
],
'timezone' => '<string>'
],
'firstUserMessage' => '<string>',
'variationId' => 'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
'systemPromptData' => [
],
'firstUserMessageData' => [
]
]
]),
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;
}HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"metadata\": {\n \"name\": \"<string>\",\n \"externalId\": \"<string>\",\n \"labels\": {}\n },\n \"spec\": {\n \"schedule\": {\n \"calendars\": [\n {\n \"second\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"minute\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"hour\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"dayOfMonth\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"month\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"dayOfWeek\": [\n {\n \"start\": 123,\n \"end\": 123,\n \"step\": 123\n }\n ],\n \"comment\": \"<string>\"\n }\n ],\n \"intervals\": [\n {\n \"every\": \"<string>\",\n \"offset\": \"<string>\"\n }\n ],\n \"timezone\": \"<string>\"\n },\n \"firstUserMessage\": \"<string>\",\n \"variationId\": \"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP\",\n \"systemPromptData\": {},\n \"firstUserMessageData\": {}\n }\n}")
.asString();{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"schedule": {
"calendars": [
{
"second": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"minute": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"hour": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfMonth": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"month": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"dayOfWeek": [
{
"start": 123,
"end": 123,
"step": 123
}
],
"comment": "<string>"
}
],
"intervals": [
{
"every": "<string>",
"offset": "<string>"
}
],
"timezone": "<string>"
},
"firstUserMessage": "<string>",
"variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
"systemPromptData": {},
"firstUserMessageData": {}
},
"info": {
"nextFireAt": "2023-11-07T05:31:56Z",
"lastFireAt": "2023-11-07T05:31:56Z",
"lastObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
"lastSkippedAt": "2023-11-07T05:31:56Z",
"lastSkipReason": "<string>",
"totalFires": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
}
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}A schedule owns the timer so you do not have to. Each fire creates an objective on the agent, with the message and prompt data you set here.
Only
Interval rules fire every fixed duration from a stable anchor, with an optional
That fires at fifteen minutes past every hour. The minimum
Objectives created by a schedule get a generated
Archiving is one-way. An archived schedule never fires and cannot be resumed, updated, or paused; create a new one instead. Pausing is idempotent, so a retried pause is safe.
spec.schedule is required, and inside it, timezone plus at least one rule.
const schedule = await client.agents.schedules.create(agentId, {
workspaceId,
metadata: { name: 'Weekday digest', externalId: 'weekday-digest' },
spec: {
firstUserMessage: 'Summarize open tickets and post the digest.',
overlapPolicy: 'OVERLAP_POLICY_SKIP',
schedule: {
timezone: 'America/New_York',
calendars: [
{ hour: [{ start: 9 }], minute: [{ start: 0 }], dayOfWeek: [{ start: 1, end: 5 }] },
],
},
},
});
console.log(schedule.state); // STATE_ACTIVE
schedule, err := client.Agents.Schedules.New(ctx, agentID,
cadenya.AgentScheduleNewParams{
WorkspaceID: cadenya.String(workspaceID),
Metadata: shared.CreateResourceMetadataParam{
Name: "Weekday digest",
ExternalID: cadenya.String("weekday-digest"),
},
Spec: cadenya.AgentScheduleSpecParam{
FirstUserMessage: cadenya.String("Summarize open tickets and post the digest."),
OverlapPolicy: cadenya.AgentScheduleSpecOverlapPolicyOverlapPolicySkip,
Schedule: cadenya.AgentScheduleSpecScheduleParam{
Timezone: cadenya.String("America/New_York"),
Calendars: []cadenya.ScheduleCalendarParam{{
Hour: []cadenya.ScheduleRangeParam{{Start: cadenya.Int(9)}},
Minute: []cadenya.ScheduleRangeParam{{Start: cadenya.Int(0)}},
DayOfWeek: []cadenya.ScheduleRangeParam{{Start: cadenya.Int(1), End: cadenya.Int(5)}},
}},
},
},
})
schedule = cadenya.agents.schedules.create(
agent_id,
workspace_id: workspace_id,
metadata: {name: "Weekday digest", externalId: "weekday-digest"},
spec: {
firstUserMessage: "Summarize open tickets and post the digest.",
overlapPolicy: :OVERLAP_POLICY_SKIP,
schedule: {
timezone: "America/New_York",
calendars: [
{hour: [{start: 9}], minute: [{start: 0}], dayOfWeek: [{start: 1, end: 5}]}
]
}
}
)
puts schedule.state # STATE_ACTIVE
curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/external_id:support/schedules" \
-H "Authorization: Bearer ${CADENYA_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"metadata": { "name": "Weekday digest", "externalId": "weekday-digest" },
"spec": {
"firstUserMessage": "Summarize open tickets and post the digest.",
"overlapPolicy": "OVERLAP_POLICY_SKIP",
"schedule": {
"timezone": "America/New_York",
"calendars": [
{ "hour": [{ "start": 9 }], "minute": [{ "start": 0 }], "dayOfWeek": [{ "start": 1, "end": 5 }] }
]
}
}
}'
Only published agents fire. A schedule on a draft agent records a skip instead of creating an objective, and unpublishing an agent pauses its schedules. The schedule still reads
STATE_ACTIVE, so a silent lack of runs usually means the agent is not published.Two kinds of rule
A schedule holds up to 16calendars and up to 16 intervals, and it fires whenever any of them matches. timezone is required and applies to both.
Calendar rules fire at wall-clock times. Each field takes a list of ranges, and the fire times are the cartesian product across fields.
{ "hour": [{ "start": 9 }], "minute": [{ "start": 0 }], "dayOfWeek": [{ "start": 1, "end": 5 }] }
offset to phase-shift within the period.
{ "intervals": [{ "every": "3600s", "offset": "900s" }] }
every is one minute (60s); anything shorter is a 400. The offset must be less than every.
The empty-field rule that catches everyone
Calendar fields do not all default the same way, and this is the one thing to get right:- Leave
second,minute, orhourempty and it means zero, the top of that unit. - Leave
dayOfMonth,month, ordayOfWeekempty and it means any.
hour and minute to fire once at 9:00. Drop the minute and it still fires once, at 9:00, because an empty minute means zero, not “every minute.” Drop the hour and you get midnight, not hourly.
A Range is { start, end, step }. end defaults to start, and step defaults to 1. So { "start": 0, "end": 23, "step": 2 } on hour is every other hour, and { "start": 9 } means 9 o’clock and nothing else. dayOfWeek runs 0 to 6 from Sunday, which makes { "start": 1, "end": 5 } Monday through Friday.
What a fire creates
Each fire calls create-objective on your behalf, carrying the schedule’s fields across:| Schedule field | Becomes |
|---|---|
firstUserMessage | The objective’s opening message. Omit it and the variation’s firstUserMessageTemplate renders instead. |
systemPromptData | The data rendered into the variation’s systemPromptTemplate. |
firstUserMessageData | The data rendered into the variation’s firstUserMessageTemplate. |
variationId | A pinned variation. Omit it and the agent’s selection mode chooses per fire. |
When the agent declares a
systemPromptDataSchema, the schedule’s systemPromptData must satisfy it. A schedule that omits it fails validation on every fire, from inside the worker. Nothing surfaces on the schedule itself.metadata.externalId shaped like schedule:<scheduleId>:<nanoseconds>, so you cannot set your own external ID on them. Find them by filtering instead:
const runs = await client.objectives.list({
workspaceId,
agentScheduleId: schedule.metadata.id, // or 'external_id:weekday-digest'
});
Overlap: skip or stack
overlapPolicy decides what happens when the previous run is still STATE_PENDING or STATE_RUNNING at fire time.
OVERLAP_POLICY_SKIPskips the fire and records why. This is the default, and it is what you want for a digest or a sweep that must not double-post.OVERLAP_POLICY_ALLOWfires anyway, so runs stack.
overlapPolicy unset stores OVERLAP_POLICY_UNSPECIFIED, which behaves as skip.
Confirm it is running
Read the schedule back withincludeInfo and info tells you what has happened.
const schedule = await client.agents.schedules.retrieve(agentId, scheduleId, {
workspaceId, includeInfo: true,
});
console.log(schedule.info?.nextFireAt); // 2026-07-09T09:00:00Z
console.log(schedule.info?.totalFires); // 2
console.log(schedule.info?.lastFireAt); // 2026-07-08T17:14:00Z
console.log(schedule.info?.lastObjectiveId); // obj_01KX1BHR0V66C77CZ075DQAPY0
console.log(schedule.info?.lastSkipReason); // "previous objective still running"
lastObjectiveId is the fastest way to see what the last run did. lastSkippedAt and lastSkipReason explain a schedule that looks active but produces nothing.
info.nextFireAt is the timestamp of the upcoming fire, computed from the spec, so you can confirm a new schedule is live before it has ever run. It is present on an active schedule with future fire times, and absent on a paused or archived one. So a fresh STATE_ACTIVE schedule reads totalFires: 0 with a real nextFireAt, which is exactly the “yes, this runs, at this time” signal a dashboard wants.
Pause, resume, archive
Lifecycle is a set of actions, not a field.state is read-only.
await client.agents.schedules.pause(agentId, scheduleId, { workspaceId }); // stop firing, keep it
await client.agents.schedules.resume(agentId, scheduleId, { workspaceId }); // start again
await client.agents.schedules.archive(agentId, scheduleId, { workspaceId }); // terminal
await client.agents.schedules.delete(agentId, scheduleId, { workspaceId }); // gone
A
PATCH that sets spec.status returns 200 and does nothing, because no such field exists. Use pause.Related
Schedule an agent
The hands-on lesson, from cadence to first fire.
Create an objective
What every fire builds, and the fields a schedule carries into it.
Agents and variations
Publishing an agent, which a schedule requires to fire.
Webhooks
Hear about a scheduled run without polling for it.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.
Example:
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Body
application/json
Create agent schedule request.
CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.
Show child attributes
Show child attributes
AgentScheduleSpec is the user-provided configuration for a schedule.
Show child attributes
Show child attributes
Response
OK
AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Show child attributes
Show child attributes
AgentScheduleSpec is the user-provided configuration for a schedule.
Show child attributes
Show child attributes
The current lifecycle state of the schedule. Output only. Schedules are created STATE_ACTIVE; use the :pause, :resume, and :archive actions to transition between states.
Available options:
STATE_UNSPECIFIED, STATE_ACTIVE, STATE_PAUSED, STATE_ARCHIVED AgentScheduleInfo provides read-only runtime data about a schedule.
Show child attributes
Show child attributes
⌘I