Create a schedule

Learn more about create a schedule.

Use the Create a schedule to create a schedule. This lets you automate recurring agent runs so you do not have to trigger them manually.

Note: The Create a schedule does not support bulk file upload.

HTTP method and endpoint

Use the following HTTP method and endpoint path to create a schedule.

POST {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.

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	`<access_token>`	Yes
`x-refresh-token`	`<refresh_token>`	Yes
`Content-Type`	application/json	Yes

Request body

The following table describes the request body parameters.


Parameter	Type	Required	Description	Accepted values / Default
name	String	Yes	The display name for the schedule.	—
query	String	Yes	The prompt or query to send to the agent on each run.	—
agent_id	String	Yes	The unique identifier of the agent to run. Get this from the List available agents operation.	—
schedule_type	String	No	How the schedule runs: recurring (on a cron expression or interval) or run-once (a single immediate run).	`recurring`, `run-once`. Default: `recurring`
cron_expression	String	No	The cron expression that defines when the agent runs, in the format minute hour day-of-month month day-of-week. Required when schedule_type is recurring and interval_minutes is not set.	—
interval_minutes	Integer	No	Runs the agent every N minutes. Required when schedule_type is recurring and cron_expression is not set.	—

Example request

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

POST {TenantURL}/ai/agentflow/api/v202605/tenant-xyz/schedules
Authorization: <access_token>
x-refresh-token: <refresh_token>
Content-Type: application/json

{
  "name": "Daily support escalation check",
  "query": "Check for support tickets requiring escalation",
  "agent_id": "my-support-agent",
  "schedule_type": "recurring",
  "cron_expression": "0 9 * * MON-FRI",
  "interval_minutes": 60
}

Response body

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


Parameter	Type	Description
`schedule_id`	String	The unique identifier of the schedule.
`tenant_id`	String	The unique identifier of the tenant.
`agent_id`	String	The unique identifier of the agent that the job or schedule runs.
`name`	String	The display name.
`query`	String	The prompt or query sent to the agent on each run.
`schedule_type`	String	The type of schedule: recurring or run-once.
`cron_expression`	String	The cron expression for the schedule, when schedule_type is recurring.
`interval_minutes`	Integer	The interval in minutes between runs, when schedule_type is recurring.
`status`	String	The status of the schedule: active, paused, running, cancelled, completed, or failed.
`next_run_at`	String	The date and time of the next scheduled run.
`last_run_at`	String	The date and time of the last run.
`run_count`	Integer	The number of times this schedule has run.
`run_once`	Boolean	Whether this is a one-time (run-once) schedule.
`last_conversation_id`	String	The unique identifier of the conversation from the most recent run.
`created_by`	String	The unique identifier of the user who created the schedule.
`created_at`	String	The date and time when the job or schedule was created.
`updated_at`	String	The date and time when the record was last updated.

Example response

The following example shows a response with successful response.

{
  "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"
}

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