Skip to content

List Scheduled Posts API

The List Scheduled Posts API returns a paginated list of scheduled posts through GET {{API_BASE_URL}}/v1/posts/scheduled/. Use it to review scheduled posts before editing, rescheduling, or cancelling them, and use limit, offset, and sort to page through results in a predictable order.

List Scheduled Posts API — GET {{API_BASE_URL}}/v1/posts/scheduled/

Call GET {{API_BASE_URL}}/v1/posts/scheduled/ to list scheduled posts. The trailing slash is part of the path. This endpoint is read-only: it returns scheduled posts and does not create, edit, reschedule, or cancel them. Use the returned postId values when you later act on a specific scheduled post through a separate operation.

Authorization

Send the token in the x-access-key header. The header name is exactly x-access-key and the value is the access token. If the header is missing or the token is invalid, treat the request as unauthenticated and do not rely on any response body, because no error contract for authentication failures was supplied for this endpoint.

Query Parameters

All three query parameters are optional. limit controls page size, offset controls how many scheduled posts to skip, and sort controls ordering direction. Before sending a request, validate limit as an integer from 1 to 100, offset as an integer of 0 or greater, and sort as exactly "asc" or "desc". Invalid values should be corrected client-side because no error contract for invalid query parameters was supplied.

Response Body

A successful request returns 200 with application/json. The top-level object contains success as a boolean, total as an integer of 0 or greater, and posts as an array of scheduled post objects. Use total to decide whether another page is needed: if offset plus the number of returned posts is less than total, request the next page by increasing offset. If posts is empty, there is nothing on the requested page even if total is greater than zero, which can happen when offset skips past the available results.

Scheduled post object fields

Each item in posts contains postId, content, scheduledFor, timezone, platforms, and createdAt as required fields, plus mediaItems as an optional field. postId identifies the scheduled post, content is the post text body, scheduledFor is the ISO 8601 scheduled datetime or null, timezone is the IANA timezone for the scheduled time, and createdAt is a date-time timestamp. Read scheduledFor together with timezone so the scheduled moment is interpreted in the intended zone, and handle null scheduledFor explicitly.

Media items

mediaItems, when present, is an array of media attachments. Each item requires type and url, and may include altText and thumbnail. type must be one of "image", "video", "gif", or "document". url must be a URI for a publicly accessible media file that can be fetched without authentication. altText, when present, must be a string of length 1 to 1000, and thumbnail, when present, must be a URI.

Platforms and status

platforms is a required array describing the target platforms and their per-platform status for the scheduled post. Each entry requires platform and status. platform must be one of "twitter", "instagram", "youtube", "tiktok", "pinterest", "linkedin", "bluesky", "facebook", "threads", or "googlebusiness". status must be one of "draft", "pending", "scheduled", "publishing", "published", "failed", or "partial". Check status per platform rather than assuming every target shares the same state.

200 application/json example

The worked example in the List scheduled posts request example shows the exact method, path, header, and query parameters. The 200 application/json response example shows the exact response shape, including the nested mediaItems and platforms structures. Replace the token placeholder with a real token only when making an actual request, and replace the example values in the response with the values returned by the endpoint.

Pagination workflow and edge cases

For pagination, start with offset 0 and a limit that fits your use case, then increase offset by the number of posts returned on each page. Keep sort consistent across pages so items do not shift between requests. If new scheduled posts are created or removed while you page, results can shift; re-check total on each response and restart from offset 0 if the list changes materially. For edge cases, validate limit, offset, and sort before sending, handle null scheduledFor, handle an empty posts array, and handle missing mediaItems as a post without media attachments.

Query parameters
ParameterRequiredTypeDefaultRange / valuesDescription
limitOptionalinteger201 <= value <= 100Page size (max 100)
offsetOptionalinteger00 <= valueNumber of scheduled posts to skip
sortOptionalstringNot supplied"asc" | "desc"Ordering direction

Exact query parameter contract for GET /v1/posts/scheduled/

Response field map
FieldRequiredTypeFormat / enum / constraintsDescription
successRequiredboolean—Top-level success flag
totalRequiredinteger0 <= valueTotal matched scheduled posts across all pages
postsRequiredarray<object>—Scheduled posts on the current page
posts[].postIdRequiredstring—MongoDB ObjectId of the Post document
posts[].contentRequiredstring—Post text body
posts[].scheduledForRequiredstring | nulldate-timeISO 8601 scheduled datetime
posts[].timezoneRequiredstring—IANA timezone for the scheduled time
posts[].mediaItemsOptionalarray<object>—Media attachments
posts[].mediaItems[].typeRequiredstring"image" | "video" | "gif" | "document"Media type
posts[].mediaItems[].urlRequiredstringuriPublicly accessible URL for the media file. Must be fetchable without authentication.
posts[].mediaItems[].altTextOptionalstring1 <= length <= 1000Accessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it.
posts[].mediaItems[].thumbnailOptionalstringuriThumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide.
posts[].platformsRequiredarray<object>—Target platforms and their statuses
posts[].platforms[].platformRequiredstring"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"Target platform
posts[].platforms[].statusRequiredstring"draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"Per-platform status
posts[].createdAtRequiredstringdate-timeCreation timestamp

Exact 200 application/json response contract

Failure and edge-case matrix
CaseCheckExpected handling
limit below 1 or above 100Validate limit as an integer in the range 1 <= value <= 100 before sendingCorrect the value client-side; do not assume a specific error response
offset below 0Validate offset as an integer of 0 or greater before sendingCorrect the value client-side; do not assume a specific error response
sort not "asc" or "desc"Validate sort against the exact enum "asc" | "desc"Correct the value client-side; do not assume a specific error response
scheduledFor is nullCheck the type of scheduledFor on every post; it is string | nullHandle null explicitly instead of parsing it as a datetime
posts is emptyCompare posts length with total and offsetTreat the requested page as empty; adjust offset or stop paging
mediaItems is absentCheck whether the optional mediaItems field is presentTreat the post as having no media attachments

Input validation and response handling checks; no additional error contract was supplied, so no new status codes or error bodies are invented

Frequently asked questions

How do I authenticate a request to list scheduled posts?

Send GET {{API_BASE_URL}}/v1/posts/scheduled/ with the x-access-key header set to your token. The endpoint returns a paginated list of scheduled posts.

How does pagination work for scheduled posts?

Use limit for page size and offset for the number of scheduled posts to skip. limit defaults to 20 and must be between 1 and 100; offset defaults to 0 and must be 0 or greater. Use sort with "asc" or "desc" to choose ordering direction.

Can scheduledFor be null?

scheduledFor is required but its type is string | null, formatted as date-time when present. Handle a null value explicitly instead of assuming every returned post has a scheduled datetime string.

How do I know whether more pages exist?

Check success, total, and posts in the 200 response. total is the total matched scheduled posts across all pages, while posts contains only the current page.

List scheduled posts request
curl -X GET "{{API_BASE_URL}}/v1/posts/scheduled/?limit=20&offset=0&sort=desc" -H "x-access-key: <token>"
200 application/json response example
{
  "success": true,
  "total": 0,
  "posts": [
    {
      "postId": "string",
      "content": "string",
      "scheduledFor": "2019-08-24T14:15:22Z",
      "timezone": "string",
      "mediaItems": [
        {
          "type": "image",
          "url": "http://example.com",
          "altText": "string",
          "thumbnail": "http://example.com"
        }
      ],
      "platforms": [
        {
          "platform": "twitter",
          "status": "draft"
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.totalinteger__2YesTotal matched scheduled posts across all pageskind: schemaRange; value: 0 <= value
response#1response.postsarray<object>__3Yes
response#1response.posts[]object__4
response#1response.posts[].postIdstring__5YesMongoDB ObjectId of the Post document
response#1response.posts[].contentstring__6YesPost text body
response#1response.posts[].scheduledForstring | null__7YesISO 8601 scheduled datetimekind: schemaFormat; value: date-time
response#1response.posts[].scheduledFor[variant1]string__7_type:stringISO 8601 scheduled datetimekind: schemaFormat; value: date-time
response#1response.posts[].scheduledFor[variant2]null__7_type:nullISO 8601 scheduled datetimekind: schemaFormat; value: date-time
response#1response.posts[].timezonestring__8YesIANA timezone for the scheduled time
response#1response.posts[].mediaItemsarray<object>__9NoMedia attachments
response#1response.posts[].mediaItems[]object__10
response#1response.posts[].mediaItems[].typestring__11Yeskind: schemaValueIn; value: "image" | "video" | "gif" | "document"
response#1response.posts[].mediaItems[].urlstring__12YesPublicly accessible URL for the media file. the service or the platform provider must be able to fetch it without authentication.kind: schemaFormat; value: uri
response#1response.posts[].mediaItems[].altTextstring__13NoAccessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it.kind: schemaLength; value: 1 <= length <= 1000
response#1response.posts[].mediaItems[].thumbnailstring__14NoThumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide.kind: schemaFormat; value: uri
response#1response.posts[].platformsarray<object>__15Yes
response#1response.posts[].platforms[]object__16
response#1response.posts[].platforms[].platformstring__17Yeskind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
response#1response.posts[].platforms[].statusstring__18Yeskind: schemaValueIn; value: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"
response#1response.posts[].createdAtstring__19Yeskind: schemaFormat; value: date-time