POST`/social-posts`

Creates and schedules one or more social posts (up to 15 per request).

https://api.postfa.st/Auth: pf-api-keyRate limit: 350 requests per day, 150 per minuteMaximum 250 MB per video and 10 MB per image.

Disabled accounts

If a post's socialMediaId points to an account whose connectionStatus is DISABLED, scheduling it returns 400 Bad Request. You can still save it as a draft (status: DRAFT). Check connectionStatus via GET /social-media/my-social-accounts first.

X (Twitter) per-account daily cap

PostFast caps X API posts per account per day: 6 on Starter, Creator, and Growth; 9 on Pro and Enterprise. An organization-wide daily X cap also applies. These are separate from the request rate limits.

Daily posting limits

Each platform has its own per-account daily posting limit, resetting at midnight UTC. See the fair usage policy at postfa.st/fair-usage for details.

Geo controls are shared across every post in a request

The controls object is applied to every post in the posts[] array. Because each geo field is platform-specific and validated per post, batch by platform when using geotags or country limits: send Facebook posts in one request and Instagram posts in another, rather than mixing platforms whose controls do not apply to the other.

Resolve place IDs with GET /social-media/search-places; the same id works as both facebookPlaceId and instagramLocationId.

Request body

postsarrayrequired

Array of post objects (1-15 per request).

contentstringrequired

Text content of the post.

mediaItemsarrayoptional

Media attached to the post.

keystringrequired

S3 object key from /file/get-signed-upload-urls.

typestringrequired

Whether the item is an image or a video.

IMAGEVIDEO

sortOrdernumberrequired

Ordering of the media items.

coverTimestampstringoptional

Millisecond timestamp used as the video cover (e.g. 5000). Supported on TikTok, Instagram Reels, and Pinterest video pins; not supported on Facebook.

coverImageKeystringoptional

S3 key of a custom video cover/thumbnail. Takes priority over coverTimestamp where supported (Instagram Reels JPEG max 8MB; Facebook Reels max 10MB; Pinterest JPEG/PNG; YouTube uses youtubeThumbnailKey; not supported on TikTok).

scheduledAtISO 8601Required (unless DRAFT)

UTC date-time, e.g. YYYY-MM-DDTHH:mm:ss.sssZ. Must be in the future, within 1 year.

socialMediaIdstring (UUID)required

Target account id from /social-media/my-social-accounts.

firstCommentstringoptional

Automatic first comment, posted ~10s after publish (up to 3 attempts). Supported on X, Instagram, Facebook, YouTube, Threads, and TikTok. On TikTok the cap is 150 chars and comments must be enabled on the post; a TikTok account that can't post comments returns firstComment.tiktok.notSupported. See the first-comment limits table below.

statusstringoptionaldefault SCHEDULED

Whether the post is scheduled or saved as a draft.

DRAFTSCHEDULED

approvalStatusstringoptionaldefault APPROVED

APPROVED publishes; PENDING_APPROVAL holds for review.

APPROVEDPENDING_APPROVAL

controlsobjectoptional

Platform-specific settings (see the controls matrix below).

Controls (platform-specific)

Optional controls object. Each field applies only to its platform; PostFast validates which controls are valid for the target account.

X (Twitter)

xRetweetUrlstringoptional

URL of a tweet to retweet without changes. Content and media are ignored when set. Accepts x.com, twitter.com, mobile.twitter.com.

Instagram

instagramPublishTypestringoptionaldefault TIMELINE

Where the media is published.

TIMELINESTORYREEL

instagramPostToGridbooleanoptionaldefault true

Also post to the profile grid.

instagramCollaboratorsstring[]optional

Instagram usernames invited as collaborators.

instagramTrialReelStrategystringoptional

Publish the reel as a trial (non-followers only). Requires instagramPublishType: REEL; cannot combine with collaborators.

MANUALSS_PERFORMANCE

instagramLocationIdstringoptional

Geotag the post with a physical place. Same numeric ID returned by /social-media/search-places (the value also used for facebookPlaceId). Works on a single image, video, reel, or story - not on carousels (2+ media items).

instagramLocationNamestringoptional

Optional display label for the location. Stored for your portal/UI; never sent to Meta.

instagramLocationId works on a single image, video, reel, or story - not on carousels (2 or more media items).

Facebook

facebookContentTypestringoptionaldefault POST

POST = up to 10 photos or 1 video; REEL = 1 video; STORY = 1 image or video.

POSTREELSTORY

facebookReelsCollaboratorsstring[]optional

Facebook usernames invited to a Reel collaboration.

facebookPlaceIdstringoptional

Geotag the post with a physical place. Numeric Facebook Page ID with location data, resolved via /social-media/search-places. Feed posts only (text/photo/carousel) - not Reels, Stories, or video posts.

facebookPlaceNamestringoptional

Optional display label for the place. Stored for your portal/UI; never sent to Meta.

facebookTargetCountriesstring[]optional

Restrict who can see the post by country. Array of ISO 3166-1 alpha-2 codes (case-insensitive), max 25, e.g. ["BG", "DE", "AT"]. Feed posts only. Can be combined with a geotag.

Geotag (facebookPlaceId) and country limit (facebookTargetCountries) both apply to feed posts only - not Reels, Stories, or video posts.

facebookTargetCountries is audience gating, not a hint: only people in the listed countries can see the post, and it is hidden from anyone not logged in to Facebook, so total reach drops.

TikTok

tiktokTitlestringoptional

Carousel title (max 90 chars, photo carousels only). When set, content becomes the description.

tiktokPrivacystringoptionaldefault PUBLIC

Deprecated. On TikTok, videos use the account's default privacy (no per-post control); photos default to public. To publish privately, save a draft with tiktokIsDraft: true. Still accepted for backward compatibility.

PUBLICMUTUAL_FRIENDSFOLLOWER_OF_CREATORONLY_ME

tiktokIsDraftbooleanoptionaldefault false

Save to TikTok drafts instead of publishing.

tiktokAllowCommentsbooleanoptionaldefault true

Allow comments.

tiktokAllowDuetbooleanoptionaldefault true

Allow duets.

tiktokAllowStitchbooleanoptionaldefault true

Allow stitches.

tiktokBrandOrganicbooleanoptionaldefault false

Your own brand promotion.

tiktokBrandContentbooleanoptionaldefault false

Paid partnership / branded content.

tiktokAutoAddMusicbooleanoptionaldefault false

Let TikTok add music automatically.

tiktokIsAigcbooleanoptionaldefault false

Disclose AI-generated content.

YouTube

youtubeTitlestringoptional

Video title (defaults to first 100 chars of content).

youtubePrivacystringoptionaldefault PUBLIC

Visibility of the video.

PRIVATEPUBLICUNLISTED

youtubeTagsstring[]optional

Video tags.

youtubeCategoryIdstringoptional

YouTube category id.

youtubeIsShortbooleanoptionaldefault true

Publish as a Short.

youtubeMadeForKidsbooleanoptionaldefault false

COPPA made-for-kids flag.

youtubePlaylistIdstringoptional

Playlist to add the video to after publishing (from /youtube-playlists). The playlist must belong to the authenticated channel; the video still publishes if the playlist addition fails.

youtubeThumbnailKeystringoptional

Custom thumbnail media key (JPEG/PNG recommended; GIF/BMP/WebP also allowed; max 2MB; 1280x720). Requires a phone-verified channel; the video still publishes if the thumbnail upload fails.

pinterestBoardIdstringRequired for Pinterest

Board to publish the pin to (from /pinterest-boards).

pinterestLinkstringoptional

Destination URL when users click the pin.

Content parsing: first line becomes the pin title (max 100 chars); the rest becomes the description (max 800).

Carousel pins support 2-5 static images (no video).

linkedinAttachmentKeystringRequired for documents

S3 key from /file/get-signed-upload-urls for a PDF/DOC/DOCX/PPT/PPTX (max 60MB). Cannot mix with mediaItems.

linkedinAttachmentTitlestringoptionaldefault Document

Display title for the document.

Google Business Profile

gbpLocationIdstringRequired for GBP

Location resource name (from /gbp-locations).

gbpTopicTypestringoptionaldefault STANDARD

Post type.

STANDARDEVENTOFFER

gbpCallToActionTypestringoptional

CTA button.

BOOKORDERSHOPLEARN_MORESIGN_UPCALL

gbpCallToActionUrlstringoptional

Destination URL for the CTA button. Used when a CTA type other than CALL is set.

gbpEventTitlestringoptional

Title for EVENT/OFFER posts (max 58 chars).

gbpEventStartDateISO 8601Required for EVENT/OFFER

Start of the event or offer.

gbpEventEndDateISO 8601Required for EVENT/OFFER

End of the event or offer.

gbpOfferCouponCodestringoptional

Coupon code (OFFER only).

gbpOfferRedeemUrlstringoptional

Redemption URL (OFFER only).

gbpOfferTermsstringoptional

Terms and conditions (OFFER only).

1 image only (JPEG/PNG), no video or carousel. Content limit 1500 chars.

Standard posts are visible for 6 months; Event and Offer posts stay until their end date.

The call-to-action button is ignored on OFFER posts.

Platform character limits

Platform	`content` cap	Notes
Facebook	63,206
X (Twitter)	4,000	Premium default; free-tier accounts are capped at 280 by X.
Instagram	2,200
LinkedIn	3,000
TikTok	4,000 / 2,200	Photo carousels: 4,000. Narrows to 2,200 if any media item is a VIDEO. See also `tiktokTitle` (max 90, photo carousels only).
YouTube	5,000	`<` and `>` are not allowed in titles or descriptions.
BlueSky	300
Threads	500
Pinterest	900	First line is the pin title (max 100); the remaining 800 chars become the description.
Telegram	4,096
Google Business Profile	1,500

Exceeding a cap returns 400 Bad Request with a contentLength.<platform> error key.

First-comment limits

Platform	`firstComment` cap
Instagram	2,200
Facebook	8,000
YouTube	10,000
Threads	500
X (Twitter)	4,000 (Premium); 280 (free tier)
TikTok	150

On TikTok, firstComment requires comments enabled on the post (tiktokAllowComments); if comments are disabled the comment is silently skipped at publish time, and a TikTok account that can't post comments returns firstComment.tiktok.notSupported. firstComment is not supported on LinkedIn, Pinterest, BlueSky, or Google Business Profile and returns a validation error.

Geo controls validation errors

Situation	Error
Geo field sent for the wrong platform	`facebookPlaceId.notSupported` / `instagramLocationId.notSupported` / `facebookTargetCountries.notSupported`
Geotag on a Facebook Reel or Story	`facebookPlaceId.contentType.notSupported`
Geotag on a Facebook video post	`facebookPlaceId.video.notSupported`
Geotag on an Instagram carousel	`instagramLocationId.carousel.notSupported`
Country limit on a Facebook Reel or Story	`facebookTargetCountries.contentType.notSupported`
More than 25 countries	`facebookTargetCountries.tooMany`
Invalid country code (not a real ISO 3166-1 alpha-2)	`400` - rejected by input validation; the message lists the allowed values
Non-numeric place/location ID	`facebookPlaceId.invalidId` / `instagramLocationId.invalidId`

The facebookPlaceName and instagramLocationName fields are optional, display-only, and stored so the place name shows in your portal. They are never sent to Meta - only the IDs and country codes are.

Response

201 Created An object with the ids of the created posts.

Request20 examples

curl -X POST "https://api.postfa.st/social-posts" \
  -H "pf-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "content": "3 productivity hacks that changed my morning routine ☀️ Which one are you trying first? #productivity #morningroutine #lifehacks",
        "mediaItems": [
          {
            "key": "video/a7b8c9d1-e2f3-4567-8901-23456789abcd.mp4",
            "type": "VIDEO",
            "sortOrder": 0,
            "coverTimestamp": "3000"
          }
        ],
        "scheduledAt": "2025-01-31T10:00:00.000Z",
        "socialMediaId": "550e8400-e29b-41d4-a716-446655440001"
      }
    ],
    "controls": {
      "tiktokPrivacy": "PUBLIC",
      "tiktokAllowComments": true,
      "tiktokAllowDuet": true
    }
  }'

Response201 Created

{
  "postIds": [
    "8d9e0f1a-2b3c-4567-8901-def123456789",
    "9e0f1a2b-3c4d-5678-9012-ef1234567890"
  ]
}

POST/social-posts