List Scheduled Posts API
The List Scheduled Posts API returns a paginated list of scheduled posts awaiting publication. Use it to review what is queued, check each post's scheduledFor time and timezone, and walk through results page by page before editing or cancelling anything.
Endpoint
Call GET {{API_BASE_URL}}/v1/posts/scheduled to retrieve scheduled posts awaiting publication. The endpoint returns one page at a time, so treat the response as a window into the full queue rather than the complete set. Start with a small limit while building a review screen, then increase it only when the interface can handle larger pages reliably.
Query Parameters
Use limit to control page size, offset to skip scheduled posts already seen, and sort to order results by scheduledFor. The default sort is "asc", which puts the next post first; use "desc" when you want the latest scheduled time first. Keep limit within 1–100, because values outside that range are invalid query parameters and should be corrected before retrying. A practical failure check is to validate limit, offset, and sort on the client before sending the request, then surface a 400 response as a request problem rather than an empty queue.
Example
The worked example in List scheduled posts with cURL requests five items starting at offset 0. After a successful response, read total to learn how many scheduled posts match across all pages, then increment offset by limit for each subsequent page until you have fetched total items. For example, with total 12 and limit 5, request offsets 0, 5, and 10; the final page contains the remaining two items. Stop when the accumulated posts reach total, and guard against infinite loops by also stopping if a page returns no posts.
Response
A successful response contains success, total, and a posts array. Each entry uses postId to identify the scheduled post, content for the post text, scheduledFor for the planned publication time, timezone for the timezone attached to that time, mediaItems for attached media, platforms for per-platform status entries, and createdAt for when the scheduled post was created. Use postId as the stable identifier for later edit or cancel operations, and use scheduledFor together with timezone when displaying the queue so reviewers do not misread the planned time. Treat total as the count across all pages, not the length of the current posts array.
Status Codes
A 200 response means the request succeeded and the paginated list can be processed. A 400 response means Invalid query parameters, so check limit, offset, and sort against the documented types, defaults, and ranges before retrying. Do not interpret a 400 as an empty queue: fix the parameters first, then request the page again.
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 20 | Page size (1–100) |
| offset | integer | 0 | Number of scheduled posts to skip |
| sort | string | "asc" | Sort by scheduledFor: "asc" (next post first) or "desc" |
Exact source contract; origin modularized as {{API_BASE_URL}}.
| Field | Type / shape in example | Description |
|---|---|---|
| success | boolean | Whether the request succeeded |
| total | integer | Total number of scheduled posts matching the filter across all pages |
| posts | array | Current page of scheduled posts |
| posts[].postId | string | Identifier for a scheduled post |
| posts[].content | string | Post content |
| posts[].scheduledFor | string | Planned publication time used for sorting |
| posts[].timezone | string | Timezone attached to scheduledFor |
| posts[].mediaItems | array | Attached media items |
| posts[].platforms | array | Per-platform entries with platform and status |
| posts[].createdAt | string | Creation time of the scheduled post |
Field names preserved exactly from source response example.
| Code | Meaning | Client action |
|---|---|---|
| 200 | Success | Process the paginated list and walk offset by limit until total items are fetched |
| 400 | Invalid query parameters | Correct limit, offset, or sort and retry; do not treat as an empty queue |
Exact source status contract.
curl "{{API_BASE_URL}}/v1/posts/scheduled?limit=5&offset=0" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"total": 12,
"posts": [
{
"postId": "post_xyz789",
"content": "A short example update.",
"scheduledFor": "2026-03-29T13:00:00.000Z",
"timezone": "America/New_York",
"mediaItems": [],
"platforms": [{ "platform": "twitter", "status": "pending" }],
"createdAt": "2026-03-28T15:00:00.000Z"
}
]
}GET {{API_BASE_URL}}/v1/posts/scheduled