Fetch items from a queue
Returns paginated queue items. Pass sessionId to get draft items from an edit session instead of live items.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
socialplanner/ category. readonlyOAuthPrivate IntegrationSub-Account TokenRequest
Headers
API Version
v3v3Path Parameters
Category queue ID
507f1f77bcf86cd799439011Body
Location ID
609e126a1c4ae1001291e1b5Edit session ID
60af88475f1b2c001f5d5f4bNumber of items to skip
0Maximum number of items to return
10To return only queue items with errors
trueItem ID to center the response around. When provided, the response will position this item in the center with items above and below based on limit. The skip parameter is ignored when itemId is provided.
60af88475f1b2c001f5d5f4bResponse
Queue items fetched successfully.
Success or Failure
trueStatus Code
201Response payload
Message
Queue items fetched successfullyList of queue items
The unique identifier of the queue item.
60af88475f1b2c001f5d5f4bThe order of the item in the queue.
1000A list of content variations for the post.
The ID of the variation.
60af88475f1b2c001f5d5f4cThe text content of the variation.
Check out our latest blog post! #marketing #socialmediaPlatform-specific mentions within the content (e.g., @username references).
Open Graph tags for link previews.
The canonical URL of the content.
https://example.comURL of the content's primary image.
https://example.com/image.pngThe title of the content.
Example TitleThe primary image URL for the post.
https://example.com/images/post-image.pngThe ID of the original post, if any.
60af88475f1b2c001f5d5f4dThe formatted post data.
Unique identifier of the post
61bb16833b3f2791f9715be2source must be one of the following values: composer, recurring, csv
composercsvrecurringreviewrsstemplate-librarycategory-queuenativecomposerLocation Id
ve9EPM428h8vShlRW1KTplatform must be one of the following values: google, facebook, instagram, linkedin, twitter, tiktok
googleDisplay date for the post
2023-08-02T00:00:00.000ZDate when the post was created
2023-08-02T00:00:00.000ZDate when the post was last updated
2023-08-02T00:00:00.000ZAccount Id
w37swmmLbA02zgqKPpxITeError
Failed due to auth tokenPlatform-specific post identifier
323534534435Direct link to view the published post on the native platform. Populated once the post is published on a platform that returns a permalink; null for posts that are not yet published (draft, scheduled, failed) or on platforms that do not return a link.
https://www.facebook.com/12345/posts/67890Aggregated engagement metrics for the published post. Populated asynchronously by the insights sync workers for supported platforms (Facebook, Instagram, LinkedIn, YouTube). Absent on posts that have not been synced yet or on platforms where insights are not supported.
Number of likes on the published post
12Number of shares of the published post
3Number of comments on the published post
5Date when the post was published
2021-06-22T05:32:49.463ZPost-level cover image (thumbnail) URL.
For posts that contain a video, this is the resolved cover image used for the first video in media[]. It is set automatically from the thumbnail provided on the first video media item at create/edit time, or auto-generated from the video when one is not supplied. Per-item thumbnails inside media[] are not retained on the response — the primary cover image lives on this field.
https://storage.googleapis.com/test/test/media/test.jpegAccount Ids
["aF3KhyL8JIuBwzK3m7Ly_iVrVJ2uoXNF0wzcBzgl5_12554616564525983496"]Content text of the post
Sample SummaryPost Media Data The limitations of media as per the platforms is provided through the reference link in API description
Public URL of the media file. Must be a valid, accessible HTTPS URL.
https://i0.wp.com/www.lifeofanarchitect.com/wp-content/uploads/2021/10/architectural-model-making-stairs.jpgAlt text or caption for the media. Used for accessibility and SEO.
Caption 1Original media URL before any processing (watermarking/optimization). Set automatically by the system.
https://storage.googleapis.com/test/test/media/original.jpegURL of the media after watermarking. Set automatically when watermark is applied.
https://storage.googleapis.com/test/test/media/watermarked.jpegMIME type of the media file. See Platform Limitations Guide for platform-specific format support.
image/jpegimage/jpgimage/pngimage/gifvideo/mp4video/movvideo/webmimage/jpegCover image URL for a video media item.
Scope
- Applies to the first video in
media[]. Values supplied on subsequent video items are ignored. - Has no effect on image-only media items.
Response behavior
- After the post is published, the resolved cover image is surfaced on the post-level
thumbnailfield of the response and is no longer echoed back insidemedia[]. This represents the post's primary cover image and the cover used for the first video.
Limitations
- Per-item thumbnails for multi-video posts are not supported. Each destination network exposes a single cover image per post for the leading video; this matches the behavior of the underlying social platform APIs.
Format
- Provide a publicly accessible JPEG or PNG URL. Animated formats and video URLs are not accepted.
- Recommended: an image matching the orientation of your video and ≤ 2 MB.
https://storage.googleapis.com/test/test/media/test.jpegDefault thumbnail URL, auto-generated from video if not provided.
https://storage.googleapis.com/test/test/media/default-thumb.jpegUnique identifier for the media item. Used for tracking and referencing.
media_abc123xyzURL of the optimized/compressed media. Set automatically when media optimization is enabled.
Enable Optimization: Set mediaOptimization: true in the post request.
https://storage.googleapis.com/your-bucket/media/optimized-image.jpgMIME type of the optimized media. May differ from original if format conversion occurred.
image/jpegFlag indicating if the media was modified (watermarked, optimized, or processed).
trueAlt text for accessibility. Supported on Instagram, Threads, Pinterest, Bluesky, and LinkedIn image posts (ignored for video and other platforms). Auto-truncated per platform: Pinterest 500, Instagram/Threads 1000, Bluesky 2000, LinkedIn 4086 chars.
A sunset over the ocean with silhouetted palm treesStatus must be one of the following values: in_progress, draft, failed, published, scheduled, in_review, notification_sent, pending, deleted
in_progressdraftfailedpublishedscheduledin_reviewnotification_sentpendingdeletedpublishedUser ID who created the post
Lx1EI6YIgQYMQi0ytFXvPost Type must be one of the following values: post, story, reel, short
poststoryreelshortpostTag Ids
["aF3KhyL8JIuBwzK3m7Ly_iVrVJ2uoXNF0wzcBzgl5_12554616564525983496"]Og Tags Meta Data
Preview image URL for the shared link.
Best Practices:
- Use high-quality images (1200x630px recommended)
- Ensure the image is publicly accessible
Auto-fetch: Use the Get Metatags API to fetch OG data from a URL.
https://yoursite.com/images/og-image.jpgURL of the webpage being shared. This is the destination when users click the link preview.
https://yoursite.com/blog/amazing-articleCustom title for the link preview. Overrides the page's og:title meta tag.
Tip: Keep titles concise (50-60 characters) for best display across platforms.
How to Double Your Social Media EngagementCustom description for the link preview. Overrides the page's og:description meta tag.
Tip: Keep descriptions under 155 characters for optimal display.
Learn proven strategies to boost your social media engagement and grow your audience.Post Approval Details
User ID of the designated approver.
Note: The approver will receive a notification when a post is submitted for review.
iVrVJ2uoXNF0wzcBzgl5Note from the post creator to the approver explaining the post or requesting specific feedback.
Please review the messaging for our Q4 campaign launch. Let me know if the CTA needs adjustment.Note from the approver to the post creator with feedback or approval comments.
Approved! Great content. Consider adding more hashtags for visibility.Current approval status of the post.
Available Values:
pending- Awaiting approver reviewapproved- Approved and ready for publishingrejected- Rejected by approver (needs revision)not_required- No approval workflow needed
pendingapprovedrejectednot_requiredpendingApprover User Details
User Id
6284c43d519161e96cc09c13Title
MrFirst name
HarryLast name
SpencerProfile photo
https://storage.googleapis.com/user/kCrjKGHZQ2/profile/1dca8c-61c9-404d-a459-751fbcb.jpegPhone number
901111119Email Id
[email protected]Tiktok Post Details
Privacy level controlling who can view the post (video or photo).
Available Values:
PUBLIC_TO_EVERYONE- Anyone can view (default)MUTUAL_FOLLOW_FRIENDS- Only mutual followers can viewSELF_ONLY- Only you can view (private)
Note: If set to SELF_ONLY, videoDisclosure must be false.
PUBLIC_TO_EVERYONEMUTUAL_FOLLOW_FRIENDSSELF_ONLYPUBLIC_TO_EVERYONEIndicates if the post (video or photo) promotes a third-party brand or product.
Required: Must be true if videoDisclosure is enabled and you're promoting another brand.
falseAllow users to comment on the post (video or photo). Default is determined by account settings.
trueAllow users to create Duet videos with your content.
Duet: Side-by-side video featuring your content and the creator's reaction/addition.
Note: Only applicable to video posts. Ignored for photo posts.
trueAllow users to create Stitch videos with your content.
Stitch: Clips up to 5 seconds of your video that creators can use in their own videos.
Note: Only applicable to video posts. Ignored for photo posts.
trueEnable branded content disclosure. Required when the post (video or photo) is promotional content.
Validations:
- Cannot be
trueifprivacyLevelisSELF_ONLY - If enabled, at least one of
promoteYourBrandorpromoteOtherBrandmust betrue
falseIndicates if the post (video or photo) promotes your own brand or product.
Required: Must be true if videoDisclosure is enabled and you're promoting your own brand.
falseShort title for TikTok photo carousel posts.
Max length: 90 UTF-16 characters
Note: Only applicable when posting images. Ignored for video posts.
Check out these highlightsAutomatically add background music to TikTok photo carousel posts.
Note: Only applicable when posting images. Ignored for video posts.
falseGMB Post Details
Google My Business post type.
Available Types:
STANDARD- Regular update post (What's New)EVENT- Event announcement with dates and titleOFFER- Promotional offer with coupon and redemption details
Required fields by type:
- STANDARD: None additional
- EVENT:
title,startDate,endDate - OFFER:
offerTitle,startDate,endDate,termsConditions,couponCode,redeemOnlineUrl
STANDARDEVENTOFFERSTANDARDEvent title. Required when gmbEventType is EVENT.
Max length: 58 characters
Summer Sale Event 2024Offer title. Required when gmbEventType is OFFER.
50% Off All ProductsStart date and time for EVENT or OFFER posts.
Required: When gmbEventType is EVENT or OFFER.
Structure:
startDate: { year, month, day }startTime: { hours, minutes, seconds }
Start Date
Year component of the date
2022Month component of the date (1-12)
1Day component of the date (1-31)
1Start Time
Hour component of the time (0-23)
23Minute component of the time (0-59)
56Second component of the time (0-59)
34End date and time for EVENT or OFFER posts.
Required: When gmbEventType is EVENT or OFFER.
Validation: Must be after startDate.
Structure:
endDate: { year, month, day }endTime: { hours, minutes, seconds }
End Date
Year component of the date
2022Month component of the date (1-12)
1Day component of the date (1-31)
1End Time
Hour component of the time (0-23)
23Minute component of the time (0-59)
56Second component of the time (0-59)
34URL to terms and conditions page. Required for OFFER posts.
https://yoursite.com/terms-and-conditionsCall-to-action URL. Required when actionType is set (except none and call).
Required for: STANDARD and EVENT posts with actionType other than none or call.
https://yoursite.com/book-nowPromotional coupon code. Required for OFFER posts.
SAVE50URL where customers can redeem the offer online. Required for OFFER posts.
https://yoursite.com/redeem-offerCall-to-action button type for the post.
Available Actions:
none- No action buttonorder- Order onlinebook- Book appointmentshop- Shop nowlearn_more- Learn morecall- Call now (no URL required)sign_up- Sign up
Note: All actions except none and call require a url.
noneorderbookshoplearn_morecallsign_upbookBluesky Post Details
Shortened links for the post (auto-generated).
Bluesky AT Protocol URI of a post to reply to.
Format: at://did:plc:{user-id}/app.bsky.feed.post/{post-id}
Use Case: Create a reply thread to an existing Bluesky post.
at://did:plc:abc123def456/app.bsky.feed.post/xyz789Bluesky AT Protocol URI of a post to quote.
Format: at://did:plc:{user-id}/app.bsky.feed.post/{post-id}
Use Case: Quote-post another user's post with your commentary.
at://did:plc:abc123def456/app.bsky.feed.post/xyz789ISO 639-1 language code for the post content.
Examples: en (English), es (Spanish), fr (French), de (German)
enExternal URL to embed as a link card in the post.
https://yoursite.com/articleTitle for the external link card. Displayed prominently in the embed.
10 Tips for Better Social Media MarketingDescription for the external link card. Brief summary displayed below the title.
Learn how to improve your social media presence with these proven strategies.User
User Id
6284c43d519161e96cc09c13Title
MrFirst name
HarryLast name
SpencerProfile photo
https://storage.googleapis.com/user/kCrjKGHZQ2/profile/1dca8c-61c9-404d-a459-751fbcb.jpegPhone number
901111119Linkedin Post Details
Title for the PDF document carousel. Displayed as the document name on LinkedIn.
Max length: 100 characters
Tip: Use a descriptive title that explains the document content.
Q4 Marketing Strategy PresentationPost images as a PDF document carousel.
Limits:
- Max 300 pages/images
- Max PDF size: 100 MB
truePublish a LinkedIn poll post.
Required fields when poll is supplied:
question(max 140 characters)options: 2 to 4 entries, eachtext≤ 30 characters; option texts must be uniquesettings.duration: one ofONE_DAY,THREE_DAYS,SEVEN_DAYS,FOURTEEN_DAYS
LinkedIn restrictions:
- Polls cannot be edited after publishing.
- A poll post cannot include
mediaor a meta-link preview.
Question for the poll. Max length: 140 characters.
Possible values: <= 140 characters
What is your favorite color?Poll options. Minimum 2, maximum 4. Each option text max 30 characters. Option texts must be unique.
Possible values: >= 2, <= 4
Text describing the option. Max length: 30 characters.
Possible values: <= 30 characters
RedPoll settings (duration).
Duration the poll stays open for votes.
ONE_DAYTHREE_DAYSSEVEN_DAYSFOURTEEN_DAYSSEVEN_DAYSPinterest Post Details
Pin title displayed on Pinterest.
Max length: 100 characters
Best Practices:
- Include relevant keywords
- Be descriptive and engaging
10 Easy Home Decor Ideas for 2024Destination URL for the pin. Users clicking the pin will be directed to this URL.
Max length: 2048 characters
Best Practices:
- Use direct links to relevant content
- Track with UTM parameters for analytics
https://yoursite.com/blog/home-decor-ideasDEPRECATED — use pinterestBoards instead. Will be removed on July 31, 2026.
Legacy mapping of Pinterest account OAuth IDs to a single board ID:
{ accountOAuthId: "boardId" }
For multi-board posting, use pinterestBoards.
Per-account Pinterest board selection. Each entry binds one connected Pinterest account to a list of boards on that account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
When supplied, this field takes precedence over the deprecated boardIds field.
Connected Pinterest account ID. Must match one of the accounts referenced in the post's userIds.
6887d6de1d8175813d50dab8Pinterest board IDs to publish to on this account. Each board produces an independent child post tracked separately for success/failure. Capped at 25 boards per account.
["987654321098765432","234567890123456789"]Shortened links for the post (auto-generated).
Facebook Post Details
Facebook post format type.
Available Types:
post- Standard feed post (images, videos, text)story- 24-hour temporary storyreel- Short-form vertical video
Restrictions:
- Reels: Require exactly 1 video, not supported on Groups
- Stories: Captions not supported
poststoryreelpostFacebook background preset ID for text-only feed posts. Facebook post only — not story or reel. Ignored when media is attached; metaLink is omitted on publish.
Validations — request returns 400 if violated:
- Must be a valid preset ID from the Facebook text background preset reference. Empty strings, whitespace-only values, and
nullare rejected. - When set,
summarymust be 130 characters or fewer.
303063890126415Instagram Post Details
Instagram post format type.
Available Types:
post- Standard feed post (images, videos, carousels)story- 24-hour temporary storyreel- Short-form vertical video (up to 90 seconds)
Restrictions:
- Media is REQUIRED for all Instagram posts
- Reels: Require exactly 1 video
- Stories: Captions not supported, JPEG only for images
poststoryreelpostCollaboration invites mapping account IDs to Instagram usernames.
Structure: { accountId: [username1, username2, username3] }
- Key: Account ID from
accountIdsarray (the Instagram account posting) - Value: Array of Instagram usernames to invite as collaborators
Get Account IDs from: Get Accounts API — use the id field from Instagram accounts.
✅ Supported for: Posts and Reels only (NOT Stories)
Validations:
- Maximum 5 collaborators per account
- No duplicate usernames allowed
- Usernames are Instagram handles without @
Use Case: Invite other Instagram users to collaborate. Once accepted, the post appears on both profiles.
Send Instagram Story via Push Notification instead of direct posting. Only applicable for Story type.
trueNote to the publisher for manual posting guidance. Only used when publishViaPushNotification is true.
When publishing, add swipe up link to the landing page so that we can direct them to the sales pageNumber of push notifications sent for this Instagram Story. Tracks how many notifications have been sent out.
1Source of where the post was marked as published. Values: "web" (web interface), "mobile" (mobile app), or null.
webmobilewebShow Reel on profile grid/feed.
✅ Applies to: Reels only
true- Reel appears on your profile gridfalse- Reel only appears in Reels tab
trueYoutube Post Details
Video title displayed on YouTube.
Max length: 100 characters
Best Practices:
- Include relevant keywords
- Be descriptive but concise
- Avoid clickbait
How to Build a Successful Marketing Strategy in 2024Video visibility/privacy setting.
Available Values:
public- Anyone can search and viewunlisted- Only people with the link can viewprivate- Only you can view
privatepublicunlistedpublicYouTube video format type.
Available Types:
video- Standard YouTube video (landscape, any duration)short- YouTube Shorts (square or vertical aspect ratio, up to 3 minutes)
Required field.
videoshortvideoCommunity Post Details
Title of the community post. Displayed as the post headline.
Max length: 1,000 characters
Required: Yes, for all Community posts.
Welcome to Our New Community Feature!Notify every member of the group when the post is published, equivalent to an @everyone broadcast prepended to the post content.
Use Case: Enable for announcements that all members should see.
Default: false
trueThe Community member each post is published as, keyed by Community account ID.
Structure: { accountId: { id, name, avatar } }
- Key — the Community account ID. This is the same value you pass in
accountIds: take it from theidfield of a Community account in the Get Accounts API, not theoauthIdfield. id(required) —contactIdof the member to publish as, from the Get Community Members API.name(optional) — display name shown as the post author.avatar(optional) — profile image URL shown against the post.
Required: Yes. Every Community account listed in accountIds must have an entry here, otherwise the request is rejected.
Member eligibility: the member must be an active member of the group and hold a role in it. This is checked again at publish time, so a member who leaves the group or loses access between scheduling and publishing causes that post to fail. Use the Validate Community Member API to confirm a stored member is still eligible before scheduling.
Private channels: list members per account rather than reusing one list across accounts — for a private channel only that channel's members may be posted as.
Pass this parameter to optimize the image media
trueList of errors associated with the queue item. Possible values: INVALID_USER_ID, PIXABAY_MEDIA.
["INVALID_USER_ID","PIXABAY_MEDIA"]The calculated date/time when this item is scheduled to be posted
2023-10-15T10:00:00.000ZThe variation index that will be used when this item is posted
0Indicates if this time slot is skipped and the post will not be published at this time
falsePagination metadata
Total count of items
100Number of items skipped (offset from start)
0Maximum number of items returned
10Trace ID for debugging
TRACE-abc123-def456