> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List schedules
> Every schedule on an agent, with its state and next fire time. The schedules dashboard read.
All the [schedules](/docs/api-reference/agentscheduleservice/create-a-new-schedule) on one agent, active and paused alike. This is what a "when does this agent run?" dashboard reads.
```typescript TypeScript theme={null}
const schedules = await client.agents.schedules.list(agentId, { workspaceId, includeInfo: true });
for await (const s of schedules) {
console.log(s.metadata.name, s.state, s.info?.nextFireAt);
}
// daily digest STATE_ACTIVE 2026-07-09T09:00:00Z
// hourly sweep STATE_PAUSED undefined
```
```go Go theme={null}
schedules := client.Agents.Schedules.ListAutoPaging(ctx, agentID,
cadenya.AgentScheduleListParams{
WorkspaceID: cadenya.String(workspaceID),
IncludeInfo: cadenya.Bool(true),
})
for schedules.Next() {
s := schedules.Current()
fmt.Println(s.Metadata.Name, s.State, s.Info.NextFireAt)
}
// daily digest STATE_ACTIVE 2026-07-09T09:00:00Z
// hourly sweep STATE_PAUSED
```
```ruby Ruby theme={null}
schedules = cadenya.agents.schedules.list(agent_id, workspace_id: workspace_id, include_info: true)
schedules.auto_paging_each do |s|
puts [s.metadata.name, s.state, s.info&.next_fire_at].join(" ")
end
# daily digest STATE_ACTIVE 2026-07-09T09:00:00Z
# hourly sweep STATE_PAUSED
```
```bash cURL theme={null}
curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/${AGENT_ID}/schedules?includeInfo=true" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
```
Unlike the archived-hiding [tool set list](/docs/api-reference/toolservice/list-tool-sets), this returns schedules in every state, so a paused schedule shows here with `STATE_PAUSED`. That is what you want for a dashboard: you need to see the paused ones to resume them.
## `nextFireAt` tells you what runs next
Pass `includeInfo: true` to get `nextFireAt`. This endpoint is one of the few where `info` is gated: without the flag, a list row carries only `createdBy` and `totalFires`, and `nextFireAt` is added when you ask. (The single-schedule [get](/docs/api-reference/agentscheduleservice/get-a-schedule-by-id) returns it either way.) The field to reach for is `nextFireAt`, the timestamp of the upcoming fire, computed from the spec:
```typescript theme={null}
s.info?.nextFireAt; // '2026-07-09T09:00:00Z' on an active schedule
s.info?.totalFires; // how many times it has fired
s.info?.lastFireAt; // when it last fired, absent before the first
s.info?.createdBy; // who made it
```
`nextFireAt` is present on a `STATE_ACTIVE` schedule with future fire times and **absent on a paused or archived one**, so its presence doubles as a live/not-live signal. Sort the list on it client-side to see what fires soonest.
A schedule with `STATE_ACTIVE` and no `nextFireAt` is one with no remaining fire times (a calendar rule whose dates have all passed). One that shows active but produces no runs is usually an [unpublished agent](/docs/api-reference/agentservice/publish-an-agent): the schedule stays active while the agent cannot fire.
## Paging
`limit` and `cursor` page the list the usual way; the SDK iterator follows the cursor. There is no state filter, so slice by state on the client:
```typescript theme={null}
const active = [];
for await (const s of await client.agents.schedules.list(agentId, { workspaceId })) {
if (s.state === 'STATE_ACTIVE') active.push(s);
}
```
## Related
The calendar and interval rules, and the full `info` surface.
The hands-on lesson, from cadence to first fire.
Why an active schedule on a draft agent produces nothing.
Filter by `agentScheduleId` to see what a schedule ran.
## OpenAPI
````yaml get /v1/workspaces/{workspaceId}/agents/{agentId}/schedules
openapi: 3.1.0
info:
title: Cadenya API
description: API for the Cadenya Agent Runtime platform.
version: '1.0'
servers:
- url: https://api.cadenya.com
description: Production server
security:
- bearerAuth: []
tags:
- name: AIProviderKeyService
- name: APIKeyService
description: |-
Issue, rotate, disable, and revoke a workspace's API keys. Every key
belongs to exactly one workspace; the system-managed global account key is
managed via GlobalAPIKeyService instead.
- name: AccountService
description: >-
Manage the authenticated account. Accounts are the top-level
organizational
unit and contain one or more workspaces.
- name: AgentScheduleService
description: >-
Manage recurring schedules attached to agents. Schedules trigger
objectives
on a cadence defined by AgentScheduleSpec.Schedule.
- name: AgentService
description: >-
Manage AI agents within a workspace. Agents define AI behavior and tool
access.
- name: AgentVariationService
description: >-
Manage variations of an agent and their tool, sub-agent, and memory layer
assignments.
- name: GlobalAPIKeyService
description: |-
Manage the account's system-provisioned global API key. The global key is
the only key that spans every workspace; it is created by the system and
cannot be deleted, so the surface is retrieve, rotate, and the
disable/enable kill switch.
- name: MemoryService
description: >-
Manage memory layers and their entries. Layers are named containers that
can
be composed into an objective's memory cascade; entries are the keyed values
within a layer. System-managed layers (e.g., episodic layers created by the
runtime) cannot be mutated through this API.
- name: ModelService
description: |-
Manage LLM models available to a workspace. Models represent provider and
family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
with the supported models and you can enable or disable each one.
- name: ObjectiveEventStreamsService
- name: ObjectiveService
- name: ProfilesService
description: |-
Operations on profiles, the account-level principals (users, API keys,
system) that authenticate against the API.
- name: SearchService
- name: TenantService
description: >-
Read and erase tenants and the subjects under them. Tenants and subjects
are
created by assertion — on objective creation or widget session mint — never
directly, so this service has no create or update: it exists to enumerate what
assertions have produced, and to destroy it on request.
- name: ToolService
description: >-
Manage tool sets and the tools they contain. Tool sets group related
tools,
and tools define specific capabilities available to agents.
When a tool set is managed, only API key actors can modify its tools; human
(profile) actors cannot.
- name: UploadService
description: |-
Issue short-lived presigned URLs for direct client-to-object-storage
uploads. Created uploads can be referenced by id when creating or updating
resources that accept binary content (e.g., MemoryEntry).
- name: WidgetService
description: |-
Manage embeddable chat widgets. A widget binds an agent to a globally
unique hostname with a per-widget origin allowlist; browsers reach it with
session tokens minted via WidgetSessionService.
- name: WidgetSessionService
description: >-
Mint and manage widget sessions. Session creation is server-to-server
only:
the customer's backend authenticates its visitor, asserts tenant/subject
context, attaches any per-visitor secrets, and receives a short-lived
bearer token the browser uses against the widget host.
- name: WorkspaceAdminService
description: >-
Administer workspaces across the account: create and archive workspaces
and
manage their membership. These operations are account-scoped and require the
admin role (a token whose profile holds the WorkOS admin role); they live
under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
tree so an admin can manage any workspace in the account, including ones they
are not themselves a member of.
- name: WorkspaceSecretService
- name: WorkspaceService
description: |-
Manage workspaces within an account. Workspaces provide organizational
grouping and isolation for resources such as agents, tools, and API keys.
This is the workspace-scoped, end-user surface. Administrative operations
(create / archive workspaces, manage members) live in WorkspaceAdminService
under /v1/account/workspaces and require the admin role.
paths:
/v1/workspaces/{workspaceId}/agents/{agentId}/schedules:
get:
tags:
- AgentScheduleService
- Agent Schedules
summary: List schedules
description: Lists all schedules for an agent
operationId: AgentScheduleService_ListAgentSchedules
parameters:
- name: workspaceId
in: path
description: Workspace ID.
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: agentId
in: path
description: >-
Agent ID. Accepts the canonical `agent_…` form or the
`external_id:` form.
required: true
schema:
example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
type: string
- name: limit
in: query
description: Maximum number of results to return.
schema:
type: integer
format: int32
- name: cursor
in: query
description: Pagination cursor from previous response.
schema:
type: string
- name: prefix
in: query
description: 'Filter expression (query param: prefix).'
schema:
type: string
- name: query
in: query
description: Free-form search query.
schema:
type: string
- name: labels
in: query
description: |-
Filters by metadata labels. Comma-separated key=value pairs,
e.g. "env=prod,team=ai". A resource matches only if every pair
matches exactly (AND semantics).
schema:
type: string
- name: sortOrder
in: query
description: Sort order for results (asc or desc by creation time).
schema:
type: string
- name: includeInfo
in: query
description: |-
When true, the `info` field on each returned schedule is populated.
Requests with this flag count more against your rate limit.
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListAgentSchedulesResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
x-codeSamples:
- lang: JavaScript
source: >-
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
// Automatically fetches more pages as needed.
for await (const agentSchedule of
client.agents.schedules.list('agent_01HXKD2E5NQM3T9AYWCFMGWT9Y', {
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
})) {
console.log(agentSchedule.metadata);
}
- lang: Python
source: |-
import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
page = client.agents.schedules.list(
agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
page = page.items[0]
print(page.metadata)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Agents.Schedules.List(\n\t\tcontext.TODO(),\n\t\t\"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y\",\n\t\tcadenya.AgentScheduleListParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n"
- lang: Ruby
source: |-
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
page = cadenya.agents.schedules.list(
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)
puts(page)
- lang: CLI
source: |-
cadenya agents:schedules list \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
components:
schemas:
ListAgentSchedulesResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AgentSchedule'
pagination:
$ref: '#/components/schemas/Page'
description: List agent schedules response.
Status:
type: object
properties:
code:
type: integer
description: >-
The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: >-
A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or
localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/GoogleProtobufAny'
description: >-
A list of messages that carry the error details. There is a common
set of message types for APIs to use.
description: >-
The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It
is used by [gRPC](https://github.com/grpc). Each `Status` message
contains three pieces of data: error code, error message, and error
details. You can find out more about this error model and how to work
with it in the [API Design
Guide](https://cloud.google.com/apis/design/errors).
AgentSchedule:
required:
- metadata
- spec
- state
type: object
properties:
metadata:
$ref: '#/components/schemas/ResourceMetadata'
spec:
$ref: '#/components/schemas/AgentScheduleSpec'
info:
$ref: '#/components/schemas/AgentScheduleInfo'
state:
readOnly: true
enum:
- STATE_UNSPECIFIED
- STATE_ACTIVE
- STATE_PAUSED
- STATE_ARCHIVED
type: string
description: >-
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.
format: enum
description: |-
AgentSchedule resource — a recurring trigger attached to an agent that
creates objectives on its cadence.
Page:
type: object
properties:
nextCursor:
type: string
description: >-
Page carries cursor-based pagination state. There is no total: the
cursor
walks the result set without ever counting it, and a count would cost a second
query on every list.
GoogleProtobufAny:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: >-
Contains an arbitrary serialized message along with a @type that
describes the type of the serialized message.
ResourceMetadata:
required:
- id
- accountId
- workspaceId
- name
- profileId
- createdAt
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"agent_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: >-
Workspace this resource belongs to for organizational grouping
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
description: ID of the actor (user or service account) that created this resource
createdAt:
readOnly: true
type: string
description: Timestamp when this resource was created
format: date-time
updatedAt:
readOnly: true
type: string
description: Timestamp when this resource was last updated
format: date-time
description: >-
Standard metadata for persistent, named resources (e.g., agents, tools,
prompts)
AgentScheduleSpec:
required:
- schedule
type: object
properties:
schedule:
allOf:
- $ref: '#/components/schemas/AgentScheduleSpec_Schedule'
description: When to fire. Required.
overlapPolicy:
enum:
- OVERLAP_POLICY_UNSPECIFIED
- OVERLAP_POLICY_ALLOW
- OVERLAP_POLICY_SKIP
type: string
description: >-
What to do when the previous run is still in flight. Defaults to
SKIP.
format: enum
firstUserMessage:
type: string
description: >-
Optional explicit first user message passed to CreateObjective on
each fire.
Becomes the first user message in the objective's chat history. When unset, the
fired objective defers to the selected variation's first_user_message_template.
variationId:
example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP
type: string
description: >-
Optional explicit variation. When unset, the agent's
variation_selection_mode
chooses per fire.
systemPromptData:
type: object
description: >-
Optional data rendered into the variation's system_prompt_template
when each
fired objective is created. If the agent has a system_prompt_data_schema,
this must satisfy it.
x-stainless-any: true
firstUserMessageData:
type: object
description: >-
Optional data rendered into the variation's
first_user_message_template when
each fired objective is created. Separate from `system_prompt_data`, which
renders the system prompt template.
x-stainless-any: true
description: AgentScheduleSpec is the user-provided configuration for a schedule.
AgentScheduleInfo:
type: object
properties:
nextFireAt:
readOnly: true
type: string
description: >-
When the schedule will next fire. Computed from the spec; absent
when
the schedule is STATE_PAUSED/STATE_ARCHIVED or has no future fire times.
format: date-time
lastFireAt:
readOnly: true
type: string
description: When the schedule last fired (regardless of objective outcome).
format: date-time
lastObjectiveId:
readOnly: true
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
description: ID of the most recent objective the schedule created.
lastSkippedAt:
readOnly: true
type: string
description: >-
When the schedule most recently skipped a fire (SKIP policy + prior
in flight).
format: date-time
lastSkipReason:
readOnly: true
type: string
description: >-
Reason for the most recent skip (e.g. "previous objective still
running").
totalFires:
readOnly: true
type: integer
description: Lifetime count of objectives created by this schedule.
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
description: AgentScheduleInfo provides read-only runtime data about a schedule.
AgentScheduleSpec_Schedule:
type: object
properties:
calendars:
type: array
items:
$ref: '#/components/schemas/Schedule_Calendar'
description: Wall-clock rules. May be empty if `intervals` is non-empty.
intervals:
type: array
items:
$ref: '#/components/schemas/Schedule_Interval'
description: Duration-based rules. May be empty if `calendars` is non-empty.
timezone:
type: string
description: >-
IANA tz name (e.g. "America/New_York"). Required. Applies to
calendars;
intervals fire on wall-clock cadence anchored in this zone.
description: >-
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.
Profile:
required:
- metadata
- spec
type: object
properties:
metadata:
$ref: '#/components/schemas/AccountResourceMetadata'
spec:
$ref: '#/components/schemas/ProfileSpec'
description: |-
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.
Schedule_Calendar:
type: object
properties:
second:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
minute:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
hour:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
dayOfMonth:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
month:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
dayOfWeek:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
comment:
type: string
description: |-
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.
Schedule_Interval:
type: object
properties:
every:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
offset:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Phase shift within `every`. Must be < `every` (enforced at runtime).
description: |-
Interval is a duration-based rule. Fires every `every` from a stable
anchor (workspace epoch), optionally phase-shifted by `offset`.
AccountResourceMetadata:
required:
- id
- accountId
- name
- profileId
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"apikey_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
createdAt:
readOnly: true
type: string
format: date-time
description: >-
AccountResourceMetadata is used to represent a resource that is
associated to an account but not to a workspace.
ProfileSpec:
required:
- type
type: object
properties:
email:
type: string
description: >-
Email address of the profile. Required and unique within an account
for
user profiles.
name:
type: string
description: Display name (e.g., "Bobby Tables").
type:
enum:
- PROFILE_TYPE_UNSPECIFIED
- PROFILE_TYPE_USER
- PROFILE_TYPE_API_KEY
- PROFILE_TYPE_SYSTEM
type: string
description: >-
Whether this profile represents a human user, an API key, or a
system
principal.
format: enum
description: Configuration for a profile.
Schedule_Range:
type: object
properties:
start:
type: integer
format: int32
end:
type: integer
format: int32
step:
type: integer
format: int32
description: |-
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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````