Schedules

Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule.

List schedules

client.Agents.Schedules.List(ctx, workspaceID, agentID, query) (*CursorPagination[AgentSchedule], error)

GET/v1/workspaces/{workspaceId}/agents/{agentId}/schedules

Create a new schedule

client.Agents.Schedules.New(ctx, workspaceID, agentID, body) (*AgentSchedule, error)

POST/v1/workspaces/{workspaceId}/agents/{agentId}/schedules

Get a schedule by ID

client.Agents.Schedules.Get(ctx, workspaceID, agentID, id) (*AgentSchedule, error)

GET/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}

Delete a schedule

client.Agents.Schedules.Delete(ctx, workspaceID, agentID, id) error

DELETE/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}

Update a schedule

client.Agents.Schedules.Update(ctx, workspaceID, agentID, id, body) (*AgentSchedule, error)

PATCH/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}

ModelsExpand Collapse

type AgentSchedule struct{…}

AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.

Metadata ResourceMetadata

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

ID string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

CreatedAt Time

Timestamp when this resource was created

formatdate-time

Name string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

ProfileID string

ID of the actor (user or service account) that created this resource

WorkspaceID string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

BundleKey stringOptional

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

ExternalID stringOptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]Optional

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

Spec AgentScheduleSpec

AgentScheduleSpec is the user-provided configuration for a schedule.

InitialMessage string

The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.

Schedule AgentScheduleSpecSchedule

Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR’d together. At least one rule is required.

Calendars []ScheduleCalendarOptional

Wall-clock rules. May be empty if intervals is non-empty.

Comment stringOptional

DayOfMonth []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

DayOfWeek []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Hour []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Minute []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Month []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Second []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Intervals []ScheduleIntervalOptional

Duration-based rules. May be empty if calendars is non-empty.

Every stringOptional

Offset stringOptional

Phase shift within every. Must be < every (enforced at runtime).

Timezone stringOptional

IANA tz name (e.g. “America/New_York”). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.

Data unknownOptional

Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.

OverlapPolicy AgentScheduleSpecOverlapPolicyOptional

What to do when the previous run is still in flight. Defaults to SKIP.

formatenum

One of the following:

const AgentScheduleSpecOverlapPolicyOverlapPolicyUnspecified AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_UNSPECIFIED"

const AgentScheduleSpecOverlapPolicyOverlapPolicyAllow AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_ALLOW"

const AgentScheduleSpecOverlapPolicyOverlapPolicySkip AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_SKIP"

Status AgentScheduleSpecStatusOptional

Lifecycle. Defaults to ACTIVE on create when unspecified.

formatenum

One of the following:

const AgentScheduleSpecStatusAgentScheduleStatusUnspecified AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_UNSPECIFIED"

const AgentScheduleSpecStatusAgentScheduleStatusActive AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ACTIVE"

const AgentScheduleSpecStatusAgentScheduleStatusPaused AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_PAUSED"

const AgentScheduleSpecStatusAgentScheduleStatusArchived AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ARCHIVED"

VariationID stringOptional

Optional explicit variation. When unset, the agent’s variation_selection_mode chooses per fire.

Info AgentScheduleInfoOptional

AgentScheduleInfo provides read-only runtime data about a schedule.

CreatedBy ProfileOptional

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

Metadata AccountResourceMetadata

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

ProfileID string

ExternalID stringOptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]Optional

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

Spec ProfileSpec

Configuration for a profile.

Type ProfileSpecType

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"

const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"

const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"

const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"

Email stringOptional

Email address of the profile. Required and unique within an account for user profiles.

Name stringOptional

Display name (e.g., “Bobby Tables”).

LastFireAt TimeOptional

When the schedule last fired (regardless of objective outcome).

formatdate-time

LastObjectiveID stringOptional

ID of the most recent objective the schedule created.

LastSkippedAt TimeOptional

When the schedule most recently skipped a fire (SKIP policy + prior in flight).

formatdate-time

LastSkipReason stringOptional

Reason for the most recent skip (e.g. “previous objective still running”).

NextFireAt TimeOptional

When the schedule will next fire. Computed from the spec; absent when the schedule is PAUSED/ARCHIVED or has no future fire times.

formatdate-time

TotalFires int64Optional

Lifetime count of objectives created by this schedule.

formatint32

type AgentScheduleInfo struct{…}

AgentScheduleInfo provides read-only runtime data about a schedule.

CreatedBy ProfileOptional

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

Metadata AccountResourceMetadata

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

ID string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

AccountID string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

Name string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

ProfileID string

ExternalID stringOptional

External ID for the resource (e.g., a workflow ID from an external system)

Labels map[string, string]Optional

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

Spec ProfileSpec

Configuration for a profile.

Type ProfileSpecType

Whether this profile represents a human user, an API key, or a system principal.

formatenum

One of the following:

const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"

const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"

const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"

const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"

Email stringOptional

Email address of the profile. Required and unique within an account for user profiles.

Name stringOptional

Display name (e.g., “Bobby Tables”).

LastFireAt TimeOptional

When the schedule last fired (regardless of objective outcome).

formatdate-time

LastObjectiveID stringOptional

ID of the most recent objective the schedule created.

LastSkippedAt TimeOptional

When the schedule most recently skipped a fire (SKIP policy + prior in flight).

formatdate-time

LastSkipReason stringOptional

Reason for the most recent skip (e.g. “previous objective still running”).

NextFireAt TimeOptional

When the schedule will next fire. Computed from the spec; absent when the schedule is PAUSED/ARCHIVED or has no future fire times.

formatdate-time

TotalFires int64Optional

Lifetime count of objectives created by this schedule.

formatint32

type AgentScheduleSpec struct{…}

AgentScheduleSpec is the user-provided configuration for a schedule.

InitialMessage string

The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.

Schedule AgentScheduleSpecSchedule

Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR’d together. At least one rule is required.

Calendars []ScheduleCalendarOptional

Wall-clock rules. May be empty if intervals is non-empty.

Comment stringOptional

DayOfMonth []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

DayOfWeek []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Hour []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Minute []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Month []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Second []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Intervals []ScheduleIntervalOptional

Duration-based rules. May be empty if calendars is non-empty.

Every stringOptional

Offset stringOptional

Phase shift within every. Must be < every (enforced at runtime).

Timezone stringOptional

IANA tz name (e.g. “America/New_York”). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.

Data unknownOptional

Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.

OverlapPolicy AgentScheduleSpecOverlapPolicyOptional

What to do when the previous run is still in flight. Defaults to SKIP.

formatenum

One of the following:

const AgentScheduleSpecOverlapPolicyOverlapPolicyUnspecified AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_UNSPECIFIED"

const AgentScheduleSpecOverlapPolicyOverlapPolicyAllow AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_ALLOW"

const AgentScheduleSpecOverlapPolicyOverlapPolicySkip AgentScheduleSpecOverlapPolicy = "OVERLAP_POLICY_SKIP"

Status AgentScheduleSpecStatusOptional

Lifecycle. Defaults to ACTIVE on create when unspecified.

formatenum

One of the following:

const AgentScheduleSpecStatusAgentScheduleStatusUnspecified AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_UNSPECIFIED"

const AgentScheduleSpecStatusAgentScheduleStatusActive AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ACTIVE"

const AgentScheduleSpecStatusAgentScheduleStatusPaused AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_PAUSED"

const AgentScheduleSpecStatusAgentScheduleStatusArchived AgentScheduleSpecStatus = "AGENT_SCHEDULE_STATUS_ARCHIVED"

VariationID stringOptional

Optional explicit variation. When unset, the agent’s variation_selection_mode chooses per fire.

type AgentScheduleSpecSchedule struct{…}

Schedule defines WHEN the schedule fires. Temporal-style structured form: a list of calendar rules (wall-clock) and/or interval rules (duration), OR’d together. At least one rule is required.

Calendars []ScheduleCalendarOptional

Wall-clock rules. May be empty if intervals is non-empty.

Comment stringOptional

DayOfMonth []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

DayOfWeek []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Hour []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Minute []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Month []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Second []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Intervals []ScheduleIntervalOptional

Duration-based rules. May be empty if calendars is non-empty.

Every stringOptional

Offset stringOptional

Phase shift within every. Must be < every (enforced at runtime).

Timezone stringOptional

IANA tz name (e.g. “America/New_York”). Required. Applies to calendars; intervals fire on wall-clock cadence anchored in this zone.

type ScheduleCalendar struct{…}

Calendar is a wall-clock rule. Empty field-list semantics:

second/minute/hour: empty means [{start: 0}] (top of the unit)
day_of_month/month/day_of_week: empty means “any value” Fire times = cartesian product across all fields.

Comment stringOptional

DayOfMonth []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

DayOfWeek []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Hour []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Minute []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Month []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

Second []ScheduleRangeOptional

End int64Optional

Start int64Optional

Step int64Optional

type ScheduleInterval struct{…}

Interval is a duration-based rule. Fires every every from a stable anchor (workspace epoch), optionally phase-shifted by offset.

Every stringOptional

Offset stringOptional

Phase shift within every. Must be < every (enforced at runtime).

type ScheduleRange struct{…}

Inclusive numeric range with optional step. {start: 9} → 9 {start: 9, end: 17} → 9..17 {start: 0, end: 59, step: 15} → 0,15,30,45 end defaults to start; step defaults to 1.

End int64Optional

Start int64Optional

Step int64Optional