Schedule and manage social media posts across TikTok, Instagram, Facebook, X (Twitter), YouTube, LinkedIn, Threads, Bluesky, Pinterest, Telegram, and Google Business Profile using the PostFast API. Use when the user wants to schedule social media posts, manage social media content, upload media for social posting, list connected social accounts, check scheduled posts, delete scheduled posts, cross-post content to multiple platforms, manage Google Business Profile posts, or automate their social media workflow. PostFast is a SaaS tool — no self-hosting required.
Schedule and manage social media posts across TikTok, Instagram, Facebook, X (Twitter), YouTube, LinkedIn, Threads, Bluesky, Pinterest, Telegram, and Google Business Profile using the PostFast API. Use when the user wants to schedule social media posts, manage social media content, upload media for social posting, list connected social accounts, check scheduled posts, delete scheduled posts, cross-post content to multiple platforms, manage Google Business Profile posts, or automate their social media workflow. PostFast is a SaaS tool — no self-hosting required.
Base URL: https://api.postfa.st
Auth header: pf-api-key: $POSTFAST_API_KEY
Important: The header name is pf-api-key (not Authorization: Bearer or x-api-key). Regenerating your key in settings permanently invalidates the previous one. See Troubleshooting if you get 403 errors.
latestMetric fields: impressions, reach, likes, comments, shares, totalInteractions, fetchedAt, extras. All numbers are strings (bigint). latestMetric is null if metrics haven't been fetched yet.
Supported platforms for analytics: Facebook, Instagram, Threads, LinkedIn, TikTok, YouTube, Pinterest. LinkedIn personal accounts are excluded. YouTube returns views, likes, comments, and total interactions (no reach or shares).
Pinterest specifics (requires a Pinterest business account):
shares — 90-day rolling save count. This is the only canonical field that isn't lifetime; Pinterest's v5 API does not expose lifetime save totals.
totalInteractions — sum of pin clicks + outbound clicks + saves + reactions + comments. Mostly lifetime, but the saves portion is 90-day, so treat it as a "best available" interaction total rather than strictly lifetime.
Refresh cadence: every 6 hours for pins under 14 days old, once a day for pins 14–60 days old. You can also trigger a manual refresh from the dashboard.
Rate limit: 350/hour.
Common Patterns
Pattern 1: Cross-platform campaign
Post the same content to LinkedIn, X, and Threads at the same time:
Optional: add a custom cover image by uploading a JPEG (max 8MB) via the same 3-step flow, then set coverImageKey in the media item. You can also set coverTimestamp (milliseconds) as a fallback frame.
Upload both video and thumbnail image, then reference the thumbnail key in controls:
# 1. Upload thumbnail image (separate from video upload)
curl -X POST https://api.postfa.st/file/get-signed-upload-urls \
-H "pf-api-key: $POSTFAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "contentType": "image/jpeg", "count": 1 }'# PUT thumbnail to signed URL# 2. Upload video (same 3-step flow as always)# 3. Create post with thumbnail key in controls:
{
"youtubeIsShort": false,
"youtubeTitle": "Full Tutorial: Social Media Strategy",
"youtubePrivacy": "PUBLIC",
"youtubeThumbnailKey": "image/abc123.jpg",
"youtubeTags": ["tutorial", "social media"],
"youtubeMadeForKids": false
}
Thumbnail specs: JPEG/PNG recommended, max 2MB, 1280x720 (16:9), min width 640px. Requires phone-verified YouTube channel. If thumbnail upload fails, the video still publishes without the custom thumbnail.
Always fetch locations first, then post with GBP-specific controls:
# Step 1: Get locations
curl -s -H "pf-api-key: $POSTFAST_API_KEY" \
https://api.postfa.st/social-media/GBP_ACCOUNT_ID/gbp-locations
# Step 2: Create a standard post with CTA# controls: { "gbpLocationId": "accounts/.../locations/...", "gbpTopicType": "STANDARD", "gbpCallToActionType": "LEARN_MORE", "gbpCallToActionUrl": "https://yoursite.com" }
Three post types: STANDARD (updates), EVENT (time-bound), OFFER (deals with coupons). EVENT and OFFER require gbpEventTitle, gbpEventStartDate, gbpEventEndDate.
Documents (PDF, PPTX, DOCX) display as swipeable carousels on LinkedIn.
Get signed URL with contentType: "application/pdf"
PUT the file to signed URL
Create post using linkedinAttachmentKey instead of mediaItems
# controls: { "linkedinAttachmentKey": "file/uuid.pdf", "linkedinAttachmentTitle": "Q1 Marketing Playbook" }# Note: mediaItems should be [] when using linkedinAttachmentKey
Pattern 8: First comment (auto-posted after publish)
Add a firstComment to any post — it's auto-posted ~10 seconds after the main post goes live (up to 3 retries):
{"posts":[{"content":"Main post text","firstComment":"Link: https://postfa.st","mediaItems":[],"scheduledAt":"...","socialMediaId":"X_ID"}],"controls":{}}
Supported on: X, Instagram, Facebook, YouTube, Threads. NOT supported on: TikTok, Pinterest, Bluesky, LinkedIn.
No platform-specific controls — text + images only
Threads
No platform-specific controls — text + images/video
Telegram
No platform-specific controls — text + images/video/mixed media
Helper Endpoints
Pinterest boards: GET /social-media/{id}/pinterest-boards → returns [{ boardId, name }]
YouTube playlists: GET /social-media/{id}/youtube-playlists → returns [{ playlistId, title }]
GBP locations: GET /social-media/{id}/gbp-locations → returns [{ id, locationId, title, address, mapsUri }]. Use locationId as gbpLocationId in controls
Connect link: POST /social-media/connect-link → returns { connectUrl }. Let clients connect accounts without a PostFast account. Params: expiryDays (1-30, default 7), sendEmail (bool), email (required if sendEmail=true)
Rate Limits
Global (per API key): 60/min, 150/5min, 300/hour, 2000/day
Per-endpoint:
POST /social-posts: 350/day
GET /social-posts: 200/hour
GET /social-posts/analytics: 350/hour
POST /social-media/connect-link: 50/hour
Platform limits:
X (Twitter) via API: 5 posts per account per day — do not exceed this
Check X-RateLimit-Remaining-* headers. 429 = rate limited, check Retry-After-* header. For batch operations, add a 1-second delay between API calls.
Media Specs Quick Reference
Platform
Images
Video
Carousel
TikTok
Carousels only
≤250MB, MP4/MOV, 3s-10min
2-35 images
Instagram
JPEG/PNG
≤1GB, 3-90s (Reels)
Up to 10
Facebook
≤30MB, JPG/PNG
1 per post
Up to 10 images
YouTube
—
Shorts ≤3min, H.264
—
LinkedIn
Up to 9
≤10min
Up to 9, or documents (PDF/PPTX/DOCX)
X (Twitter)
Up to 4
—
—
Pinterest
2:3 ratio ideal
Supported
2-5 images
Google Business Profile
1 image (JPEG/PNG, 5MB max)
Not supported
—
Bluesky
Up to 4
Not supported
—
Threads
Supported
Supported
Up to 10
Telegram
Up to 10
Supported
Up to 10 mixed media
Common Gotchas
Always fetch accounts first — socialMediaId is a UUID, not a platform name. Call GET /social-media/my-social-accounts to get valid IDs.
Media MUST go through 3-step upload — No external URLs. Always: get signed URL → PUT to S3 → use the key in mediaItems.
scheduledAt must be in the future — ISO 8601 UTC format. Past dates return 400.
Pinterest ALWAYS requires pinterestBoardId — Fetch boards first with GET /social-media/{id}/pinterest-boards.
TikTok requires video for standard posts — Images only work in carousels (2-35 images).
LinkedIn documents use linkedinAttachmentKey — NOT mediaItems. Set mediaItems: [] when posting documents.
Content-Type on S3 PUT must match — The Content-Type header in your S3 PUT must match what you requested in get-signed-upload-urls.
Instagram Reels need video 3-90 seconds — Outside this range returns an error.
YouTube Shorts need video under 3 minutes — H.264 codec with AAC audio recommended.
X (Twitter) has a 280 character limit — Longer content is silently truncated.
Cross-posting shares controls — The controls object applies to ALL posts in the batch. Platform-irrelevant controls are ignored.
X (Twitter) API limit is 5 posts/account/day — Exceeding this risks account restrictions.
firstComment only works on 5 platforms — X, Instagram, Facebook, YouTube, Threads. TikTok, Pinterest, Bluesky, LinkedIn return a validation error.
Retweets ignore content/media — When xRetweetUrl is set, the content and mediaItems fields are ignored.
LinkedIn documents support PDF, DOC, DOCX, PPT, PPTX — Max 60MB. Cannot mix with regular media.
Pagination is 0-based — page=0 returns the first page. Response pageInfo.page shows 1-based display number.
Instagram trial reels require instagramPublishType: "REEL" — Setting instagramTrialReelStrategy without it returns 400. Also cannot be combined with instagramCollaborators.
YouTube custom thumbnails require phone verification — youtubeThumbnailKey only works if the YouTube channel is phone-verified. If it fails, the video still publishes without the custom thumbnail.
GBP ALWAYS requires gbpLocationId — Fetch locations first with GET /social-media/{id}/gbp-locations. Use the locationId field (not id).
GBP supports only 1 image — No video, no carousels. JPEG/PNG, max 5MB.
GBP EVENT/OFFER posts require dates — gbpEventStartDate and gbpEventEndDate are required when gbpTopicType is EVENT or OFFER.
GBP content limit is 1,500 characters — Shorter than most platforms.
GBP posts expire — Standard posts auto-expire after 6 months. Event/Offer posts expire at their end date.
coverTimestamp is milliseconds — e.g., "5000" = 5 seconds into the video. Not seconds.
coverImageKey platform limits — Instagram Reels: JPEG only, max 8MB. Facebook Reels: any format, max 10MB. Pinterest video: JPEG/PNG. NOT supported on TikTok (use coverTimestamp) or YouTube (use youtubeThumbnailKey).
Facebook Reels don't support coverTimestamp — Only coverImageKey works for FB Reel covers. coverTimestamp is ignored.
Troubleshooting
403 "Missing organizationId or activeWorkspaceId"
This is the most common error. It means the API didn't recognize your key. Check these in order:
Wrong header name. The header must be exactly pf-api-key. Not Authorization: Bearer, not x-api-key, not api-key. Example:
Env var not set. If $POSTFAST_API_KEY isn't set in your shell, the literal string $POSTFAST_API_KEY gets sent as the key value. Verify it's set:
echo$POSTFAST_API_KEY# Should print a 44-character base64 string ending with "="
If empty, re-export it. If you're using a .env file, make sure your tool actually loads it (dotenv, direnv, etc.). Shell quoting matters: use double quotes around the value if it contains special characters.
Regenerated key. Each time you click "Generate API Key" in PostFast settings, the previous key is permanently invalidated. Only regenerate if the old key is compromised. If you regenerated and are still using the old key, that's why it fails.
Wrong key entirely. Your PostFast API key is a 44-character base64 string ending with =. Don't confuse it with keys from other services (OpenAI sk-proj-..., Stripe sk_live_..., etc.).
401 Invalid or missing API key
The pf-api-key header is either missing from the request or the value is empty. Double-check that your HTTP client is actually sending the header (some tools strip custom headers on redirects).
429 Rate limit exceeded
You've hit the per-workspace rate limit. Check the Retry-After-Minute, Retry-After-5Minutes, Retry-After-Hour, or Retry-After-Day response header for when you can retry. Limits: 60/min, 150/5min, 300/hour, 2,000/day.
# Auth
Header: pf-api-key: $POSTFAST_API_KEY
# List accounts
GET /social-media/my-social-accounts
# Schedule post
POST /social-posts { posts: [{ content, mediaItems, scheduledAt, socialMediaId, firstComment? }], status?, approvalStatus?, controls: {} }
# Draft post (no scheduledAt needed)
POST /social-posts { posts: [...], status: "DRAFT", controls: {} }
# List posts (page is 0-based, limit max 50)
GET /social-posts?page=0&limit=20
GET /social-posts?page=0&limit=50&platforms=X,LINKEDIN&statuses=SCHEDULED&from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z
# Delete post
DELETE /social-posts/:id
# Upload media (3 steps)
POST /file/get-signed-upload-urls { contentType, count }
PUT <signedUrl> (raw file, matching Content-Type)
# then use key in mediaItems
# Pinterest boards
GET /social-media/:id/pinterest-boards
# YouTube playlists
GET /social-media/:id/youtube-playlists
# GBP locations
GET /social-media/:id/gbp-locations
# Post analytics (published posts with metrics)
GET /social-posts/analytics?startDate=...&endDate=...&platforms=...
# Connect link (for clients)
POST /social-media/connect-link { expiryDays?, sendEmail?, email? }
Tips for the Agent
Always call my-social-accounts first to get valid socialMediaId values.
For media posts, complete the full 3-step upload flow (signed URL → S3 PUT → create post).
scheduledAt must be ISO 8601 UTC and in the future.
LinkedIn documents use linkedinAttachmentKey instead of mediaItems.
For carousels, include multiple items in mediaItems with sequential sortOrder.
Video cover images: use coverImageKey in mediaItems for IG Reels, FB Reels, Pinterest video. Use coverTimestamp (milliseconds) for TikTok. YouTube uses youtubeThumbnailKey in controls.
When cross-posting, adjust content length for each platform's limits (X: 280, Bluesky: 300, TikTok: 2200, GBP: 1500).
If the user doesn't specify a time, suggest tomorrow at 9:00 AM in their timezone.
Batch up to 15 posts per API call for efficiency.
Use firstComment for CTAs and links — keeps the main post clean and gets better engagement.
X (Twitter) allows only 5 posts per account per day via API — warn the user if they're batching many X posts.
For draft posts, set status: "DRAFT" and omit scheduledAt — the user can finalize in the PostFast dashboard.
GBP always requires gbpLocationId — fetch locations first with GET /social-media/{id}/gbp-locations.
GBP supports 3 post types: STANDARD (default), EVENT, and OFFER. EVENT/OFFER need start and end dates.
GBP only supports 1 image (no video, no carousels) and has a 5-post/day limit.
Use GET /social-posts with from/to filters to check what's already scheduled before adding more.
