List schedules

Learn more about list schedules.

Use the List schedules to review and audit every schedule in the tenant in one place.

HTTP method and endpoint

Use the following HTTP method and endpoint path to list schedules.

GET {TenantURL}/ai/agentflow/api/v202605/{tenant_id}/schedules

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`TenantURL`	String	Yes	The base URL for your tenant.
`tenant_id`	String	Yes	The unique identifier of your tenant.

Query parameters

The following table describes the query parameters and their values.


Parameter	Type	Required	Description	Accepted values / Default
`status`	String	No	Returns only schedules with this status. .	Accepted values: active, paused, running, cancelled, completed, failed
`agent_id`	String	No	Returns only results for this agent.	—
`schedule_type`	String	No	Returns only schedules of this type.	Accepted values / Default: recurring, run-once.
`search`	String	No	Returns only schedules whose name or query contains this text.	—
`limit`	Integer	No	The maximum number of schedules to return per page.	Default: `50`
`page_token`	String	No	The page token from a previous response. Omit to get the first page.	—

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes

Request body

This operation does not require a request body.

Example request

Use the following example to see how a complete request is structured, with headers.

GET {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/schedules
Authorization: <access_token>

Response body

The following table describes the fields returned in the response body.


Parameter	Type	Description
`schedules`	Array	The schedules in the current page of results.
`schedules[].schedule_id`	String	The unique identifier of the schedule.
`schedules[].tenant_id`	String	The unique identifier of the tenant.
`schedules[].agent_id`	String	The unique identifier of the agent that the schedule runs.
`schedules[].name`	String	The display name of the schedule.
`schedules[].query`	String	The prompt or query sent to the agent on each run.
`schedules[].schedule_type`	String	The type of schedule: recurring or run-once.
`schedules[].cron_expression`	String	The 5-field cron expression for the schedule, when `schedule_type` is recurring.
`schedules[].interval_minutes`	Integer	The interval in minutes between runs, when schedule_type is recurring.
`schedules[].status`	String	The status of the schedule: active, paused, running, cancelled, completed, or failed.
`schedules[].next_run_at`	String	The date and time of the next scheduled run.
`schedules[].last_run_at`	String	The date and time of the last run.
`schedules[].run_count`	Integer	The number of times this schedule has run.
`schedules[].run_once`	Boolean	Whether this is a one-time (run-once) schedule. When true, the schedule runs once. When false, the schedule is recurring.
`schedules[].last_conversation_id`	String	The unique identifier of the conversation from the most recent run.
`schedules[].created_by`	String	The unique identifier of the user who created the schedule.
`schedules[].created_at`	String	The date and time when the schedule was created.
`schedules[].updated_at`	String	The date and time when the record was last updated.
`pagination`	Object	Pagination details for the current page of results.
`pagination.total_count`	Integer	The number of items in the current page of results.
`pagination.next_page_token`	String	The token to pass as page_token to get the next page of results. Empty when this is the last page.
`pagination.limit`	Integer	The maximum number of items per page.

Example response

The following example shows a successful response.

{
  "schedules": [
    {
      "schedule_id": "sched-abc123",
      "tenant_id": "tenant-xyz",
      "agent_id": "my-support-agent",
      "name": "Daily support escalation check",
      "query": "Check for support tickets requiring escalation",
      "schedule_type": "recurring",
      "cron_expression": "0 9 * * MON-FRI",
      "interval_minutes": 60,
      "status": "active",
      "next_run_at": "2025-05-14T09:00:00Z",
      "last_run_at": "2025-05-13T09:00:00Z",
      "run_count": 5,
      "run_once": false,
      "last_conversation_id": "conv-abc123",
      "created_by": "user@example.com",
      "created_at": "2025-05-01T10:00:00Z",
      "updated_at": "2025-05-13T15:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 1,
    "next_page_token": "null",
    "limit": 50
  }
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.


HTTP status	Description	Recommended action
`422 Unprocessable Entity`	Validation Error	Review the request parameters or body, correct the invalid values, and resend the request.

Unify and manage your data