Scheduling Posts
Retrieving Posts
Learn how to query and retrieve your scheduled and published posts across all platforms using the Postpone API.
Overview
The Postpone API provides GraphQL queries to retrieve your posts across all supported platforms. Each platform has two types of queries:
- Single post query — Fetch a specific post by its ID.
- Submissions listing query — List submissions with filtering, sorting, and pagination.
Use the single post query when you know the post ID (e.g., after scheduling). Use the submissions listing query to browse, search, and filter your posts.
Single Post Queries
Fetch a single post by its unique ID. Each platform has its own query:
| Platform | Query |
|---|---|
redditPost(id: ID!) | |
| X/Twitter | twitterPost(id: ID!) |
instagramPost(id: ID!) | |
facebookPost(id: ID!) | |
| Threads | threadsPost(id: ID!) |
| Bluesky | blueskyPost(id: ID!) |
| TikTok | tiktokPost(id: ID!) |
| YouTube | youtubePost(id: ID!) |
linkedinPost(id: ID!) | |
pinterestPost(id: ID!) | |
| Mastodon | mastodonPost(id: ID!) |
| Tumblr | tumblrPost(id: ID!) |
Example
query TwitterPost($id: ID!) {
twitterPost(id: $id) {
id
socialAccount {
id
username
}
submissions {
id
text
postAt
url
result {
id
dateSubmitted
likes
comments
views
}
error {
errorCode
message
}
}
}
}
{
"id": "12345"
}
{
"data": {
"twitterPost": {
"id": "12345",
"socialAccount": {
"id": "678",
"username": "myhandle"
},
"submissions": [
{
"id": "99001",
"text": "Check out our latest blog post!",
"postAt": "2025-12-15T14:30:00.000Z",
"url": "https://twitter.com/myhandle/status/123456789",
"result": {
"id": "55001",
"dateSubmitted": "2025-12-15T14:30:05.000Z",
"likes": 42,
"comments": 7,
"views": 1250
},
"error": null
}
]
}
}
}
All single post queries return
null if the post is not found or you don't have access to it.Listing Submissions
List submissions with pagination, filtering, and sorting. Each platform has its own submissions query:
| Platform | Query |
|---|---|
redditSubmissions | |
| X/Twitter | twitterSubmissions |
instagramSubmissions | |
facebookSubmissions | |
| Threads | threadsSubmissions |
| Bluesky | blueskySubmissions |
| TikTok | tiktokSubmissions |
| YouTube | youtubeSubmissions |
linkedinSubmissions | |
pinterestSubmissions | |
| Mastodon | mastodonSubmissions |
| Tumblr | tumblrSubmissions |
Example
query TwitterSubmissions(
$startDate: DateTime
$endDate: DateTime
$socialAccountIds: [ID]
$search: String
$sortField: SortFieldType
$page: Int
$limit: Int
$submissionType: SubmissionType
$postTags: [ID]
$publishingStatus: PublishingStatusType
) {
twitterSubmissions(
startDate: $startDate
endDate: $endDate
socialAccountIds: $socialAccountIds
search: $search
sortField: $sortField
page: $page
limit: $limit
submissionType: $submissionType
postTags: $postTags
publishingStatus: $publishingStatus
) {
total
objects {
id
text
postAt
url
result {
id
dateSubmitted
likes
comments
views
}
error {
errorCode
message
}
}
}
}
{
"startDate": "2025-12-01T00:00:00.000Z",
"endDate": "2025-12-31T23:59:59.000Z",
"submissionType": "SUBMITTED",
"sortField": "DATE",
"page": 1,
"limit": 10
}
{
"data": {
"twitterSubmissions": {
"total": 47,
"objects": [
{
"id": "99001",
"text": "Check out our latest blog post!",
"postAt": "2025-12-15T14:30:00.000Z",
"url": "https://twitter.com/myhandle/status/123456789",
"result": {
"id": "55001",
"dateSubmitted": "2025-12-15T14:30:05.000Z",
"likes": 42,
"comments": 7,
"views": 1250
},
"error": null
}
]
}
}
}
Common Filtering Parameters
The following parameters are shared across all submission listing queries:
startDate
DateTime
Filter submissions scheduled from this date onward. When
submissionType is SUBMITTED, filters by the submission date instead.endDate
DateTime
Filter submissions scheduled until this date. When
submissionType is SUBMITTED, filters by the submission date instead.socialAccountId
ID
Filter by a specific social account ID.
socialAccountIds
[ID]
Filter by multiple social account IDs.
search
String
Search text within post content.
sortField
SortFieldType
Sort results by a specific field. Valid values:
DATE, LIKES, COMMENTS.page
Int
Page number for pagination. Default:
1.limit
Int
Number of results per page. Default:
25.submissionType
SubmissionType
Filter by submission status. Valid values:
ALL, SCHEDULED, SUBMITTED, FAILED.postTags
[ID]
Filter by post tag IDs. Use the
postTags query to retrieve available tag IDs.publishingStatus
PublishingStatusType
Filter by publishing status. Valid values:
READY_TO_PUBLISH, DRAFT. Default: READY_TO_PUBLISH.Some platforms may have additional platform-specific parameters beyond the common ones listed above (e.g.,
rootsOnly for Twitter threads, subreddits for Reddit).Pagination
All submission listing queries return a paginated response with two fields:
total
Int
The total number of submissions matching the query filters across all pages.
objects
[Submission]
An array of submission objects for the current page.
To paginate through results, increment the page parameter while keeping the same limit:
# Page 1: first 25 results
twitterSubmissions(page: 1, limit: 25) { total objects { id } }
# Page 2: results 26-50
twitterSubmissions(page: 2, limit: 25) { total objects { id } }
Use the
total field to calculate the number of pages: totalPages = ceil(total / limit).