Skip to content

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.

Query parameters
ParameterTypeDefaultDescription
limitinteger20Page size (1–100)
offsetinteger0Number of scheduled posts to skip
sortstring"asc"Sort by scheduledFor: "asc" (next post first) or "desc"

Exact source contract; origin modularized as {{API_BASE_URL}}.

Response fields
FieldType / shape in exampleDescription
successbooleanWhether the request succeeded
totalintegerTotal number of scheduled posts matching the filter across all pages
postsarrayCurrent page of scheduled posts
posts[].postIdstringIdentifier for a scheduled post
posts[].contentstringPost content
posts[].scheduledForstringPlanned publication time used for sorting
posts[].timezonestringTimezone attached to scheduledFor
posts[].mediaItemsarrayAttached media items
posts[].platformsarrayPer-platform entries with platform and status
posts[].createdAtstringCreation time of the scheduled post

Field names preserved exactly from source response example.

Status codes
CodeMeaningClient action
200SuccessProcess the paginated list and walk offset by limit until total items are fetched
400Invalid query parametersCorrect limit, offset, or sort and retry; do not treat as an empty queue

Exact source status contract.

List scheduled posts with cURL
curl "{{API_BASE_URL}}/v1/posts/scheduled?limit=5&offset=0" \
  -H "x-access-key: YOUR_API_KEY"
Example scheduled posts response
{
	"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"
		}
	]
}
Contract example 1
GET {{API_BASE_URL}}/v1/posts/scheduled