Skip to content

DX-2174: enhance schedule API response fields and update documentation #546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 8, 2025
Merged

DX-2174: enhance schedule API response fields and update documentation #546

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c1c5d32
feat: enhance schedule API response fields and update documentation
CahidArda Oct 7, 2025
4d7b840
feat: update schedule API response examples with new fields and values
CahidArda Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 63 additions & 16 deletions qstash/api/schedules/get.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,30 +13,30 @@ authMethod: "bearer"

## Response

<ResponseField name="createdAt" type="int" required>
The creation time of the object. UnixMilli
</ResponseField>
<ResponseField name="scheduleId" type="string" required>
The id of the schedule.
</ResponseField>
<ResponseField name="cron" type="string" required>
The cron expression used to schedule the message.
</ResponseField>
<ResponseField name="callerIP" type="string" required>
IP address where this schedule created from.
<ResponseField name="createdAt" type="int" required>
The creation time of the object. UnixMilli
</ResponseField>
<ResponseField name="destination" type="string" required>
Url or URL Group name
</ResponseField>
<ResponseField name="method" type="string" required>
The HTTP method to use for the message.
</ResponseField>
<ResponseField name="header" type="Record<string, string[]>" required>
<ResponseField name="header" type="Record<string, string[]>">
The headers of the message.
</ResponseField>
<ResponseField name="body" type="string" required>
<ResponseField name="body" type="string">
The body of the message.
</ResponseField>
<ResponseField name="bodyBase64" type="string">
The base64 encoded body of the message.
</ResponseField>
<ResponseField name="retries" type="int">
The number of retries that should be attempted in case of delivery failure.
</ResponseField>
Expand All @@ -46,6 +46,45 @@ authMethod: "bearer"
<ResponseField name="callback" type="string">
The url where we send a callback to after the message is delivered
</ResponseField>
<ResponseField name="failureCallback" type="string">
The url where we send a callback to after the message delivery fails
</ResponseField>
<ResponseField name="callerIp" type="string">
IP address where this schedule was created from.
</ResponseField>
<ResponseField name="isPaused" type="boolean" required>
Whether the schedule is paused or not.
</ResponseField>
<ResponseField name="flowControlKey" type="string">
The flow control key for rate limiting.
</ResponseField>
<ResponseField name="parallelism" type="int">
The maximum number of parallel executions.
</ResponseField>
<ResponseField name="rate" type="int">
The rate limit for this schedule.
</ResponseField>
<ResponseField name="period" type="int">
The time interval during which the specified rate of requests can be activated using the same flow control key. In seconds.
</ResponseField>
<ResponseField name="retryDelayExpression" type="string">
The retry delay expression for this schedule, if retry_delay was set when creating the schedule.
</ResponseField>
<ResponseField name="label" type="string">
The label assigned to the schedule for filtering purposes.
</ResponseField>
<ResponseField name="lastScheduleTime" type="int">
The timestamp of the last scheduled execution.
</ResponseField>
<ResponseField name="nextScheduleTime" type="int">
The timestamp of the next scheduled execution.
</ResponseField>
<ResponseField name="lastScheduleStates" type="Record<string, string>">
The states of the last scheduled messages. Maps message id to state (IN_PROGRESS, SUCCESS, FAIL).
</ResponseField>
<ResponseField name="callerIP" type="string">
The IP address of the caller who created the schedule.
</ResponseField>

<RequestExample>

Expand Down Expand Up @@ -93,16 +132,24 @@ defer resp.Body.Close()
<ResponseExample>
```json 200 OK
{
"scheduleId": "scd_1234",
"createdAt": 1623345678001,
"cron": "0 0 1 * *",
"destination": "https://example.com",
"method": "POST",
"header": {
"Content-Type": ["application/json"]
createdAt: 1754565618803,
scheduleId: "schedule-id",
cron: "* * * * *",
destination: "https://your-website/api",
method: "GET",
header: {
"Content-Type": [ "application/json" ],
},
retries: 3,
delay: 25,
lastScheduleTime: 1755095280020,
nextScheduleTime: 1759909800000,
lastScheduleStates: {
msg_7YoJxFpwk: "SUCCESS",
},
"body": "{\"message\":\"hello\"}",
"retries": 3
callerIP: "127.43.12.54",
isPaused: true,
parallelism: 0,
}
```
</ResponseExample>
84 changes: 65 additions & 19 deletions qstash/api/schedules/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,37 +9,75 @@ authMethod: "bearer"

<ResponseField name="array" type="Object[]">

<ResponseField name="createdAt" type="int" required>
The creation time of the object. UnixMilli
</ResponseField>
<ResponseField name="id" type="string" required>
<ResponseField name="scheduleId" type="string" required>
The id of the schedule.
</ResponseField>
<ResponseField name="cron" type="string" required>
The cron expression used to schedule the message.
</ResponseField>
<ResponseField name="createdAt" type="int" required>
The creation time of the object. UnixMilli
</ResponseField>
<ResponseField name="destination" type="string" required>
Url or URL Group (topic) name
</ResponseField>

<ResponseField name="method" type="string" required>
The HTTP method to use for the message.
</ResponseField>
<ResponseField name="header" type="Record<string, string[]>" required>
<ResponseField name="header" type="Record<string, string[]>">
The headers of the message.
</ResponseField>
<ResponseField name="body" type="string" required>
<ResponseField name="body" type="string">
The body of the message.
</ResponseField>
<ResponseField name="retries" type="int" >
<ResponseField name="retries" type="int">
The number of retries that should be attempted in case of delivery failure.
</ResponseField>
<ResponseField name="delay" type="int" >
<ResponseField name="delay" type="int">
The delay in seconds before the message is delivered.
</ResponseField>
<ResponseField name="callback" type="string">
<ResponseField name="callback" type="string">
The url where we send a callback to after the message is delivered
</ResponseField>
<ResponseField name="failureCallback" type="string">
The url where we send a callback to after the message delivery fails
</ResponseField>
<ResponseField name="callerIp" type="string">
IP address where this schedule was created from.
</ResponseField>
<ResponseField name="isPaused" type="boolean" required>
Whether the schedule is paused or not.
</ResponseField>
<ResponseField name="flowControlKey" type="string">
The flow control key for rate limiting.
</ResponseField>
<ResponseField name="parallelism" type="int">
The maximum number of parallel executions.
</ResponseField>
<ResponseField name="rate" type="int">
The rate limit for this schedule.
</ResponseField>
<ResponseField name="period" type="int">
The time interval during which the specified rate of requests can be activated using the same flow control key. In seconds.
</ResponseField>
<ResponseField name="retryDelayExpression" type="string">
The retry delay expression for this schedule, if retry_delay was set when creating the schedule.
</ResponseField>
<ResponseField name="label" type="string">
The label assigned to the schedule for filtering purposes.
</ResponseField>
<ResponseField name="lastScheduleTime" type="int">
The timestamp of the last scheduled execution.
</ResponseField>
<ResponseField name="nextScheduleTime" type="int">
The timestamp of the next scheduled execution.
</ResponseField>
<ResponseField name="lastScheduleStates" type="Record<string, string>">
The states of the last scheduled messages. Maps message id to state (IN_PROGRESS, SUCCESS, FAIL).
</ResponseField>
<ResponseField name="callerIP" type="string">
The IP address of the caller who created the schedule.
</ResponseField>
</ResponseField>

<RequestExample>
Expand Down Expand Up @@ -89,16 +127,24 @@ defer resp.Body.Close()
```json 200 OK
[
{
"scheduleId": "scd_1234",
"createdAt": 1623345678001,
"cron": "0 0 1 * *",
"destination": "https://example.com",
"method": "POST",
"header": {
"Content-Type": ["application/json"]
createdAt: 1754565618803,
scheduleId: "schedule-id",
cron: "* * * * *",
destination: "https://your-website/api",
method: "GET",
header: {
"Content-Type": [ "application/json" ],
},
retries: 3,
delay: 25,
lastScheduleTime: 1755095280020,
nextScheduleTime: 1759909800000,
lastScheduleStates: {
msg_7YoJxFpwk: "SUCCESS",
},
"body": "{\"message\":\"hello\"}",
"retries": 3
callerIP: "127.43.12.54",
isPaused: true,
parallelism: 0,
}
]
```
Expand Down