Skip to main content
GET
JavaScript
All the schedules on one agent, active and paused alike. This is what a “when does this agent run?” dashboard reads.
Unlike the archived-hiding tool set list, 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 returns it either way.) The field to reach for is nextFireAt, the timestamp of the upcoming fire, computed from the spec:
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: 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:

Create a schedule

The calendar and interval rules, and the full info surface.

Schedule an agent

The hands-on lesson, from cadence to first fire.

Publish an agent

Why an active schedule on a draft agent produces nothing.

List objectives

Filter by agentScheduleId to see what a schedule ran.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

agentId
string
required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

Query Parameters

limit
integer<int32>

Maximum number of results to return.

cursor
string

Pagination cursor from previous response.

prefix
string

Filter expression (query param: prefix).

query
string

Free-form search query.

labels
string

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).

sortOrder
string

Sort order for results (asc or desc by creation time).

includeInfo
boolean

When true, the info field on each returned schedule is populated. Requests with this flag count more against your rate limit.

Response

OK

List agent schedules response.

items
object[]
pagination
object

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.