---
title: "Previews a schedule occurrence."
method: POST
path: "/agents/{agentId}/schedules/nextoccurrence"
tags: ["agentSchedules"]
---

# Previews a schedule occurrence.

`POST /agents/{agentId}/schedules/nextoccurrence`

Calculates the next occurrence for the supplied cadence without changing the schedule.

<Check title="Required Permissions" icon="key">Any authenticated user.</Check>

## Path parameters

- `agentId` string, uuid, required

## Request body

- AgentScheduleNextOccurrenceRequestModel — Represents the cadence used to preview the next scheduled agent run.
  - `cronRule` string, required — The cron rule used for recurring execution.
  - `recurrenceInterval` integer, required — The number of matching cron occurrences between scheduled runs.
  - `timezone` string, required — The IANA timezone used to evaluate the cron rule.
  - `scheduleId` string, uuid, nullable — The optional existing schedule whose current cadence phase is used.

## Response `200`

OK

- AgentScheduleNextOccurrenceResponseModel — Represents the next scheduled agent run preview.
  - `nextRunOn` string, date-time — The next selected occurrence in UTC.
  - `isFirstRun` boolean — Whether the occurrence starts a new cadence phase.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `503` — Service Unavailable

## Changes

- **2026-09-20** `5332322ffca3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/awork-io/apis/api-v1-reference/changes/agents/:agentId/schedules/nextoccurrence/post.md)

---

[API](https://skmtc.dev/awork-io/apis/api-v1-reference.md) · [All operations](https://skmtc.dev/awork-io/apis/api-v1-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/awork-io/apis/api-v1-reference/revisions/eadefd26df12?raw)