Upload-Post SDK for Python
Official Python client for the Upload-Post API - Cross-platform social media upload.
Upload videos, photos, text posts, and documents to TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, X (Twitter), Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop, and Listmonk with a single API.
Installation
pip install upload-post
Quick Start
from upload_post import UploadPostClient
client = UploadPostClient("YOUR_API_KEY")
# Upload a video to multiple platforms
response = client.upload_video(
"video.mp4",
title="Check out this awesome video! 🎬",
user="my-profile",
platforms=["tiktok", "instagram", "youtube"]
)
print(response)
Features
- ✅ Video Upload - TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Bluesky, Discord, Telegram, X, Mastodon, WordPress
- ✅ Photo Upload - TikTok, Instagram, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, X, Mastodon, Lemmy, WordPress
- ✅ Text Posts - X, LinkedIn, Facebook, Threads, Reddit, Bluesky, Discord, Telegram, Slack, Mastodon, Nostr, Lemmy, Dev.to, Hashnode, WordPress, Whop, Listmonk
- ✅ Document Upload - LinkedIn (PDF, PPT, PPTX, DOC, DOCX)
- ✅ Scheduling - Schedule posts for later
- ✅ Posting Queue - Add posts to your configured queue
- ✅ First Comments - Auto-post first comment after publishing
- ✅ Analytics - Get engagement metrics
- ✅ Audience - Who follows a profile, per platform
- ✅ Suggestions - Hashtags and searches to post about, per platform
- ✅ Comments - Read, reply, moderate; replies under a comment on TikTok, Threads, YouTube, Instagram, Facebook and LinkedIn
- ✅ Direct Messages - Instagram, Messenger, WhatsApp and Bluesky
- ✅ AutoDM rules - Account-wide Instagram comment/story/keyword DMs
- ✅ Webhook deliveries - 7-day delivery log and redelivery
- ✅ Full Type Hints
API Reference
Upload Video
response = client.upload_video(
"video.mp4",
title="My awesome video",
user="my-profile",
platforms=["tiktok", "instagram", "youtube"],
# Optional: Schedule for later
scheduled_date="2024-12-25T10:00:00Z",
timezone="Europe/Madrid",
# Optional: Add first comment
first_comment="Thanks for watching! 🙏",
# Optional: Platform-specific settings
disable_comment=False, # TikTok
media_type="REELS", # Instagram
privacyStatus="public", # YouTube
tags=["tutorial", "coding"], # YouTube
)
Upload Photos
# Upload single or multiple photos
response = client.upload_photos(
["photo1.jpg", "photo2.jpg", "https://example.com/photo3.jpg"],
title="Check out these photos! 📸",
user="my-profile",
platforms=["instagram", "facebook", "x"],
# Optional: Add to queue instead of posting immediately
add_to_queue=True,
# Platform-specific
media_type="IMAGE", # Instagram: IMAGE or STORIES
facebook_page_id="your-page-id",
)
Upload Text Posts
response = client.upload_text(
title="Just shipped a new feature! 🚀 Check it out at example.com",
user="my-profile",
platforms=["x", "linkedin", "threads"],
# Optional: Create a poll on X
poll_options=["Option A", "Option B", "Option C"],
poll_duration=1440, # 24 hours in minutes
# Optional: Post to a LinkedIn company page
target_linkedin_page_id="company-page-id",
)
Upload Documents (LinkedIn)
response = client.upload_document(
"presentation.pdf",
title="Q4 2024 Report",
user="my-profile",
description="Check out our latest quarterly results!",
visibility="PUBLIC",
target_linkedin_page_id="company-page-id", # Optional: post to company page
)
Check Upload Status
For async uploads, check the status using the request_id:
status = client.get_status("request_id_from_upload")
print(status)
For scheduled or queued posts, check the status using the job_id:
status = client.get_job_status("job_id_from_scheduled_post")
print(status)
Get Upload History
history = client.get_history(page=1, limit=20)
print(history)
Scheduled Posts
# List all scheduled posts
scheduled = client.list_scheduled()
# Edit a scheduled post
client.edit_scheduled(
"job-id",
scheduled_date="2024-12-26T15:00:00Z",
timezone="America/New_York",
)
# Fix the text in place (only the platforms listed change)
client.edit_scheduled(
"job-id",
platform_content={"instagram": {"caption": "New Instagram caption"}},
)
# Change any other option by its API form name (None removes it), schedule the
# video natively on YouTube, or replace the Reels cover
client.edit_scheduled(
"job-id",
fields={"privacyStatus": "unlisted", "disable_comment": True},
youtube_publish_at="2026-11-01T09:00:00Z",
cover_image_base64="data:image/jpeg;base64,...", # or remove_cover=True
)
# Cancel a scheduled post
client.cancel_scheduled("job-id")
User Management
# List all profiles
users = client.list_users()
# Create a new profile
client.create_user("new-profile")
# Delete a profile
client.delete_user("old-profile")
# Generate JWT for platform integration (white-label)
jwt = client.generate_jwt(
"my-profile",
redirect_url="https://yourapp.com/callback",
platforms=["tiktok", "instagram"],
# Optional: force the connection page language for this profile.
# Supported: "en", "es", "de", "fr", "pt", "pl", "tr". When omitted, the page
# auto-detects the visitor's browser language and falls back to English.
language="es",
# Optional: override individual connection-page strings. Flat dict of i18n
# dot-path keys to strings. Max 100 entries, keys ^[a-zA-Z0-9_.]+$, values
# up to 300 chars. Echoed back in the "profile" object of validate_jwt.
ui_labels={
"connect.title": "Link your accounts",
"connect.subtitle": "Publish everywhere from one place",
},
)
Get Analytics
analytics = client.get_analytics(
"my-profile",
platforms=["instagram", "tiktok"],
)
print(analytics)
# Instagram returns two audience breakdowns with the same shape
# ("age", "gender", "country", "city"):
print(analytics["analytics"]["instagram"]["follower_demographics"])
print(analytics["analytics"]["instagram"]["engaged_audience_demographics"])
Post Analytics and TikTok drafts
# Every platform the upload went to, or just one of them
stats = client.get_post_analytics("REQUEST_ID")
tiktok = client.get_post_analytics("REQUEST_ID", platform="tiktok")
# Any post of the account by its native id (e.g. one returned by get_media)
client.get_post_analytics_by_platform_id("7412345678901234567", "tiktok", "my-profile")
A TikTok upload sent to drafts (post_mode="MEDIA_UPLOAD" or
tiktok_upload_to_draft=True) has no post until the creator publishes it from
the TikTok app. Call get_post_analytics(request_id) after that: Upload-Post
asks TikTok which post came from the draft, then returns its metrics and fills
in platform_post_id and post_url.
- While the draft is still in the inbox,
post_metrics_errorsays so. That answer is reused for a while (about 5 minutes for a fresh upload, up to 6 hours for one several days old); after 30 days without a post Upload-Post stops asking. - TikTok only gives the post id once the post is public and moderated. A draft published as private never gets per-post analytics.
- TikTok rows carry
original_publish_id(the upload's TikTokpublish_id), here and inget_cached_post_analytics.post_urlis empty when the account's @username is not known.
Cached Post Analytics
Replays per-post metrics already fetched, instead of calling the platforms again. Only contains posts previously fetched through a live per-post endpoint; there is no background refresh, so captured_at is the last time that post was read live. Not subject to the live calls, so it is not subject to the live post-analytics rate limit (100 requests / 5 minutes). Use it to page through a profile's post history.
cursor = None
while True:
page = client.get_cached_post_analytics(
"my-profile",
platform="youtube", # optional: instagram, tiktok, youtube, facebook, linkedin, threads, pinterest, reddit
limit=50, # default 50, max 200
since="2026-06-01", # defaults to 30 days ago
until="2026-07-01", # defaults to today
cursor=cursor,
)
for post in page["posts"]:
print(post["platform"], post["post_id"], post["metrics"])
cursor = page["next_cursor"]
if not cursor:
break
Get Media
Retrieve recent posts from a connected social account. Supported platforms:
instagram, tiktok, youtube, linkedin, facebook, x, threads,
pinterest, bluesky, reddit.
# Personal LinkedIn profile (default for non-org accounts):
media = client.get_media("linkedin", "my-profile")
# Force the personal profile of an account connected as an org admin:
media = client.get_media("linkedin", "my-profile", page_urn="me")
# Target a specific LinkedIn organization page:
media = client.get_media("linkedin", "my-profile", page_urn="12345")
The response carries a pagination object — {"limit": ..., "next_cursor": ..., "has_more": ...}, with next_cursor None and has_more False on the last
page:
cursor = None
while True:
page = client.get_media("instagram", "my-profile", limit=50, cursor=cursor)
print(len(page["media"]))
cursor = page["pagination"]["next_cursor"]
if not cursor:
break
limit defaults to 25 and is clamped to 1-100, with per-platform caps of 20 for
TikTok and 50 for YouTube. LinkedIn, Discord and Telegram do not support
cursors — they accept limit only, and passing a cursor returns HTTP 400.
Helper Methods
# Get Facebook pages for a profile
fb_pages = client.get_facebook_pages("my-profile")
# Get LinkedIn pages for a profile
li_pages = client.get_linkedin_pages("my-profile")
# Resolve any LinkedIn company Page to the urn + exact name a mention needs
org = client.resolve_linkedin_organization(
"my-profile", "https://www.linkedin.com/company/linkedin/"
)
print(org["urn"], org["name"], org["mention"]) # urn:li:organization:1337 LinkedIn @[LinkedIn](urn:li:organization:1337)
# Get Pinterest boards for a profile
boards = client.get_pinterest_boards("my-profile")
# TikTok: trending Commercial Music Library tracks
music = client.get_tiktok_trending_music(
"my-profile", genre="POP", country_code="ES", date_range="7DAY"
)
# TikTok: find a track by song or artist
found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES")
# TikTok: search locations to tag
locations = client.get_tiktok_locations("my-profile", "Madrid")
Comments
The same methods cover every platform that has comments — Instagram, Facebook,
YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
answers one question and platform says who to ask.
# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
comments = client.get_post_comments(
user="my-profile",
platform="tiktok",
post_id="7412345678901234567",
limit=20,
)
# Read the replies hanging from one of them — same question, one more parameter
replies = client.get_post_comments(
user="my-profile",
platform="tiktok",
post_id="7412345678901234567",
comment_id="7412345678909999999",
)
# Same on Instagram, Facebook and LinkedIn (company Pages). On LinkedIn pass the
# comment_urn from the listing; a bare id is only looked up in the first 250.
replies = client.get_post_comments(
user="my-profile",
platform="linkedin",
post_id="urn:li:share:7500811262105264139",
comment_id="urn:li:comment:(urn:li:activity:7500811262105264139,7503818768586981376)",
)
# Comment on the post, or reply to a comment
client.create_comment(
user="my-profile",
platform="tiktok",
post_id="7412345678901234567",
message="Thanks for watching!",
)
client.create_comment(
user="my-profile",
platform="tiktok",
comment_id="7412345678909999999",
message="Glad you liked it",
)
# Delete one
client.delete_comment(
user="my-profile", platform="tiktok", comment_id="7412345678909999999"
)
You can also have the first comment posted for you right after publishing, with
first_comment for every platform or tiktok_first_comment for TikTok alone.
On TikTok all of this needs the comments capability, which the account grants
when it connects — see
What a TikTok connection can do.
Replies (comment_id) work on TikTok, Threads, YouTube, Instagram, Facebook and
LinkedIn (company Pages only); post_id is still required. X and Bluesky answer
platform_not_supported. Error codes you can branch on with
UploadPostError.error_code:
error_code |
Status | Meaning |
|---|---|---|
invalid_comment_id |
400 | Wrong format (Instagram: digits; Facebook: {post}_{comment}; LinkedIn: digits or the comment_urn) |
invalid_cursor |
400 | LinkedIn replies: after must be the number from next_cursor |
comment_not_found |
404 | Instagram/Facebook do not know the comment (one without replies is a 200 with an empty list) |
linkedin_comment_not_found |
404 | Bare LinkedIn id not among the post's first 250 comments: pass the comment_urn |
linkedin_personal_not_supported |
403 | Personal LinkedIn profile: LinkedIn only lets us read company Pages |
linkedin_page_access_denied |
403 | The member who connected LinkedIn is no longer an admin of the Page |
Moderating a comment: hide, like, pin
comment_action() does the three and undoes them, on any platform that
supports it. Each action carries its own inverse, and post_id is only sent
when the platform needs it:
client.comment_action(
user="my-profile", platform="tiktok", action="hide",
comment_id="7412345678909999999", post_id="7412345678901234567",
)
client.comment_action(
user="my-profile", platform="tiktok", action="like",
comment_id="7412345678909999999",
)
client.comment_action(
user="my-profile", platform="tiktok", action="unpin",
comment_id="7412345678909999999", post_id="7412345678901234567",
)
action |
Undo | post_id |
|---|---|---|
hide |
unhide |
required |
like |
unlike |
not sent |
pin |
unpin |
required |
Direct Messages
One pair of methods for every messaging platform: instagram, facebook
(Messenger), whatsapp and bluesky. send_dm also sends from your own
Telegram bot (platform="telegram") to people who started it; reading Telegram
conversations is not available yet.
# Instagram: by the person's Instagram-scoped id, inside the 24-hour window
client.send_dm("my-profile", "instagram", recipient_id="1784...", message="Thanks!")
# Bluesky: by handle, DID or profile link. Links, #hashtags and @mentions are clickable
sent = client.send_dm(
"my-profile", "bluesky",
recipient_id="alice.bsky.social",
message="Our new guide: https://example.com/guide",
)
# Share a Bluesky post, reply to a message, or act on one (no DM quota used)
client.send_dm("my-profile", "bluesky", recipient_id="alice.bsky.social",
message="Look at this",
attachments={"type": "post", "url": "https://bsky.app/profile/alice.bsky.social/post/3l5t..."})
client.send_dm("my-profile", "bluesky", conversation_id=sent["conversation_id"],
sender_action="react", message_id=sent["message_id"], reaction="🔥")
client.send_dm("my-profile", "bluesky", conversation_id=sent["conversation_id"],
sender_action="mark_read")
# Read conversations (Bluesky: at most 25 per page)
page = client.get_dm_conversations("my-profile", "bluesky", messages_limit=5)
for convo in page["conversations"]:
print(convo["id"], convo.get("status"), convo.get("unread_count"))
# Bluesky-only filters: one conversation and its older messages, requests, unread
client.get_dm_conversations("my-profile", "bluesky", conversation_id="3l5ttwb6ycx2f",
messages_cursor="...")
client.get_dm_conversations("my-profile", "bluesky", status="request", read_state="unread")
Any other /dms/send field (WhatsApp template, location, contacts,
list, cta_url; Messenger tag, template...) goes through as a keyword
argument. Bluesky DMs need an app password created with "Allow access to your
direct messages" (Bluesky > Settings > Privacy and security > App passwords),
then reconnect Bluesky with it; otherwise the API answers 403
bluesky_dm_scope_missing. Other Bluesky codes:
error_code |
Status | Meaning |
|---|---|---|
bluesky_recipient_unavailable |
403 | The recipient does not accept your DM (reason: MessagesDisabled, NotFollowedBySender, BlockedActor...). No quota used |
bluesky_recipient_not_found / bluesky_conversation_not_found / bluesky_post_not_found |
404 | Unknown handle, conversation or shared post |
bluesky_message_too_long |
400 | More than 1000 characters. Nothing sent |
bluesky_rejected |
400 | Bluesky refused it (e.g. a reaction that is not a single emoji) |
bluesky_reauth_required |
401 | Reconnect Bluesky |
bluesky_rate_limited |
429 | Wait retry_after seconds |
bluesky_chat_unavailable / bluesky_edge_rate_limited |
502 / 503 | Nothing was sent; retry later |
bluesky_send_unconfirmed |
504 | It may have been sent. Do not retry automatically: read the conversation first |
New DMs (Instagram, Messenger, WhatsApp and Bluesky) can also reach you as the
opt-in dm_received webhook. Bluesky has no push, so Upload-Post checks every
5 minutes.
AutoDM rules (whole Instagram account)
A rule answers comments on every post and reel of the account (present and future), plus story replies, story mentions and keyword DMs. Rules never expire and work only from Meta's real-time notifications.
rule = client.create_autodm_rule(
profile_username="my-profile",
reply_message="Here is your free guide!",
triggers=["comment", "story_reply", "story_mention", "dm_keyword"],
trigger_keywords=["guide"], # required for dm_keyword
buttons=[{"title": "Get the guide", "url": "https://example.com/guide"}],
per_user_cooldown_hours=24, # 0-720; never < 24 for story/DM triggers
)["rule"]
for r in client.list_autodm_rules("my-profile")["rules"]:
print(r["rule_id"], r["status"], r["webhook"]["receiving_events"], r["webhook"].get("hint"))
client.pause_autodm_rule(rule["rule_id"])
client.resume_autodm_rule(rule["rule_id"])
client.delete_autodm_rule(rule["rule_id"])
- Up to 10 rules per Instagram account; they do not count towards the 2-monitors-per-day limit. A post with its own monitor is answered by that monitor only.
- Pace: 25 DMs per account every 15 minutes plus the plan's daily DM allowance; what does not fit is queued for up to 24 hours.
- Errors: 409
duplicate_rule/rule_limit_reached/rule_creation_in_progress, 502webhook_subscription_failed(reconnect Instagram), 503account_rules_disabled, 409rule_stoppedon resume when the account left its profile.
Audience
Where the analytics methods answer how did my posts do, get_audience()
answers who is following me. One endpoint, one platform parameter, like
every other question in the API.
audience = client.get_audience(
user="my-profile",
platform="tiktok",
start_date="2026-07-01",
end_date="2026-07-30",
)
print(audience["range"]) # the window actually used
print(audience["audience"]["countries"]) # and "cities", "ages", "genders"
print(audience["activity_by_hour"]) # [{"hour": "14", "followers_online": 1494}, ...]
print(audience["followers_daily"]) # [{"date", "total", "new", "lost"}, ...]
print(audience["profile_actions"]) # bio link, address, email, phone, leads
print(audience["bio_description"])
The window is clamped on the server: at most 60 days, and end_date always
before today. A wider window is trimmed to what the platform accepts instead of
failing.
Ask for a benchmark_category and the same call also returns how the account
compares with the average of that category. The accepted categories come back in
benchmark_categories on every response, so a picker needs no second call:
categories = client.get_audience(
user="my-profile", platform="tiktok"
)["benchmark_categories"]
benchmark = client.get_audience(
user="my-profile", platform="tiktok",
benchmark_category="SOFTWARE_AND_APPS",
)["benchmark"]
print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
Suggestions
get_suggestions() answers what is worth posting about: the hashtags or the
searches a platform suggests around a keyword. One endpoint for both, told apart
by type.
hashtags = client.get_suggestions(
user="my-profile", platform="tiktok", type="hashtags",
q="pilates", country_code="ES", language="es",
)["hashtags"]
print(hashtags) # [{"name": ..., "view_count": ...}, ...]
keywords = client.get_suggestions(
user="my-profile", platform="tiktok", type="keywords", q="pilates",
)["keywords"]
Per-post numbers stay in get_post_analytics(). On TikTok that response carries
more than the usual counters: retention (the curve, second by second),
impression_sources (For You, search, profile...), audience_types (followers
vs non-followers), new_followers, reach and the watch times.
Asking a platform a question it cannot answer fails with
platform_not_supported and the list of the ones that can.
Webhooks: configuration, delivery log and redelivery
# Turn the webhook on and opt into the inbound events
client.update_notification_config(
webhook_url="https://example.com/upload-post",
webhook_events=["upload_completed", "dm_received", "comment_received"],
channels={"webhook": True},
)
print(client.get_notification_config()["notifications"]["webhook_secret"])
# Did an event reach my server? (7-day history, newest first)
failed = client.list_webhook_deliveries(status="failed", limit=20, include_payload=True)
for d in failed["deliveries"]:
print(d["delivery_id"], d["event"], d["attempt_count"], d["last_status_code"], d["last_error"])
# One delivery with its exact payload, and send it again
one = client.get_webhook_delivery(failed["deliveries"][0]["delivery_id"])
again = client.redeliver_webhook(one["delivery"]["delivery_id"])
print(again["delivery"]["delivery_id"], again["delivery"]["redelivery_of"])
Webhooks are delivered at least once: a timeout, connection error, 5xx,
408 or 429 is retried with the same body and the same
X-Upload-Post-Delivery id (6 attempts over about 8.5 hours, header
X-Upload-Post-Attempt 1-6); other 4xx answers are final. Deduplicate by
X-Upload-Post-Delivery. A redelivery is a new delivery with its own id and
X-Upload-Post-Redelivery-Of. Filters of list_webhook_deliveries: event,
status (pending, delivered, failed, cancelled), request_id,
job_id, profile_username, limit (1-100), page (1-50). redeliver_webhook
answers 409 webhook_removed / event_unsubscribed / blocked_url when there
is nowhere to send it.
Team members (acting on the owner's account)
client = UploadPostClient("MEMBER_API_KEY", act_as_user="owner@example.com")
client.list_users() # the owner's profiles
Every request carries X-Act-As-User. If the owner's current plan no longer
covers your seat (the last invited members are suspended after a downgrade,
never removed), requests fail with status_code 403 and error_code
"TEAM_SEAT_SUSPENDED"; access comes back by itself when the owner upgrades or
frees a seat.
list_team_members() (owner) and list_shared_accounts() (member) show who is
on the team and suspended / suspended_reason. Profile webhooks:
get_profile_webhook, set_profile_webhook, delete_profile_webhook; also
delete_notification_webhook() and rotate_webhook_secret().
Post actions, best times, queue, Telegram, Bluesky and Google Business
Editing and reposting published posts, the best time to post, the queue, and
the management endpoints of Telegram, Bluesky and Google Business are plain
methods: the required arguments are positional and every other keyword is
sent to the API with its API name, nothing is dropped. A file field (file,
photo, animation, sticker, avatar, banner, telegram_media...) given
as a local path, bytes or an open file turns the request into
multipart/form-data; URLs and Telegram file_ids stay strings. Each method
links to its page in the API docs for the full list of fields.
# Best hours to post on Instagram, and a queue that fills them by itself
best = client.get_best_times("my-profile", "instagram", top=3)
client.update_queue_settings("my-profile", slots="auto", auto_slots_count=3,
auto_platforms=["instagram", "tiktok"])
# Telegram: pin a post, copy it to another chat, delete every message of an album
client.edit_post("my-profile", "telegram", "42", action="pin")
client.repost_post("my-profile", "telegram", "42", mode="copy", target_chat_id="@other_channel")
client.unpublish_post("my-profile", "telegram", "42", delete_all_messages=True)
# Telegram chat management
client.create_telegram_invite_link("my-profile", name="Newsletter", creates_join_request=True)
client.update_telegram_chat_info("my-profile", photo="logo.jpg") # multipart
# Bluesky: bookmark a post, read notifications, save a draft
client.post_action("my-profile", "bluesky", "bookmark", post_id="at://did:plc:.../app.bsky.feed.post/3l...")
notifications = client.get_bluesky_notifications("my-profile", limit=20)
client.create_bluesky_draft("my-profile", posts=[{"text": "Coming soon"}])
# Google Business: reviews, gallery, daily metrics, strict location edits
reviews = client.list_google_business_reviews("my-shop", page_size=20)["reviews"]
client.reply_to_google_business_review("my-shop", "Thank you!", review_name=reviews[0]["name"])
client.upload_google_business_media("my-shop", file="dining-room.jpg", category="INTERIOR")
client.get_google_business_performance("my-shop", metrics=["call_clicks", "website_clicks"],
start_date="2026-10-01", end_date="2026-10-31")
client.update_google_business_location_info("my-shop", edit_mode="strict", dry_run=True,
phone="+34 900 000 000")
Telegram analytics come from get_analytics("my-profile", platforms=["telegram"])
(subscribers or members, reactions, boosts), and Telegram DMs from your own bot
go through send_dm(platform="telegram", ...).
Posts: edit, repost, actions
| Method | Endpoint | What it does |
|---|---|---|
edit_post |
POST /api/uploadposts/posts/edit |
Edit a published post (Facebook, LinkedIn, X, Google Business, Telegram: text, buttons, pin/unpin, stop a poll, live location, replace the media). |
repost_post |
POST /api/uploadposts/posts/repost |
Repost / reshare a post (LinkedIn, X, Threads; Telegram forward or copy with mode, post_ids, all_messages). |
post_action |
POST /api/uploadposts/posts/action |
Act on a published post: Telegram reactions and forward/copy; Bluesky bookmark/unbookmark, pin/unpin, reply and quote settings, detach/reattach quotes. |
save_post |
POST /api/uploadposts/posts/save |
Save a post: a Pinterest Pin to a board, or a Bluesky bookmark (platform: "bluesky"). |
Best time to post and queue
| Method | Endpoint | What it does |
|---|---|---|
get_best_times |
GET /api/uploadposts/best-times |
Best hours to publish for a connected account, with source and confidence (timezone, top, refresh, page_urn, facebook_page_id). |
get_queue_settings |
GET /api/uploadposts/queue/settings |
Queue settings, including slots_mode, auto_slots and effective_slots. |
update_queue_settings |
POST /api/uploadposts/queue/settings |
Update the queue. slots: "auto" (or slots_mode: "auto") fills the best hours automatically (auto_slots_count, auto_platforms, refresh); a slots array switches back to fixed slots. |
get_queue_preview |
GET /api/uploadposts/queue/preview |
Upcoming queue slots and what is scheduled in each (count, max 50). |
get_next_queue_slot |
GET /api/uploadposts/queue/next-slot |
Next free queue slot. |
mark_queue_slot_full |
POST /api/uploadposts/queue/slot-full |
Mark a queue slot (ISO 8601, UTC) as full. |
unmark_queue_slot_full |
DELETE /api/uploadposts/queue/slot-full |
Unmark a queue slot marked as full. |
Telegram: chat, members and invite links
| Method | Endpoint | What it does |
|---|---|---|
get_telegram_chat_info |
GET /api/uploadposts/telegram/chat-info |
Chat details, subscribers/members and administrators (include_administrators, return_bots). |
update_telegram_chat_info |
PATCH /api/uploadposts/telegram/chat-info |
Change the chat title, description, photo (file or photo_url), permissions, slow mode, sticker set... |
get_telegram_boosts |
GET /api/uploadposts/telegram/boosts |
Boosts of the chat (with user_id: that user's boosts). |
get_telegram_member |
GET /api/uploadposts/telegram/members |
Read one member (user_id) or list the administrators. |
moderate_telegram_member |
POST /api/uploadposts/telegram/members |
Ban, unban, restrict, promote or give a custom title to a member (action). |
create_telegram_invite_link |
POST /api/uploadposts/telegram/invite-links |
Create an invite link (name, expiry, member limit, join requests, subscription). |
edit_telegram_invite_link |
PATCH /api/uploadposts/telegram/invite-links |
Edit an invite link. |
revoke_telegram_invite_link |
DELETE /api/uploadposts/telegram/invite-links |
Revoke an invite link. |
create_telegram_primary_invite_link |
POST /api/uploadposts/telegram/invite-links/primary |
Generate a new primary invite link (the previous one stops working). |
answer_telegram_join_request |
POST /api/uploadposts/telegram/join-requests |
Approve or decline a request to join the chat. |
get_telegram_topic_icons |
GET /api/uploadposts/telegram/topics/icons |
Custom emoji that can be used as forum topic icons. |
create_telegram_topic |
POST /api/uploadposts/telegram/topics |
Create a forum topic. |
edit_telegram_topic |
PATCH /api/uploadposts/telegram/topics |
Edit, close, reopen, hide, unhide or unpin a forum topic. |
delete_telegram_topic |
DELETE /api/uploadposts/telegram/topics |
Delete a forum topic. |
unpin_all_telegram_messages |
POST /api/uploadposts/telegram/unpin-all |
Unpin every message of the chat (or of a topic). |
leave_telegram_chat |
POST /api/uploadposts/telegram/leave |
Make the bot leave the connected chat. |
answer_telegram_suggested_post |
POST /api/uploadposts/telegram/suggested-posts |
Approve or decline a suggested post in a channel direct messages chat. |
get_telegram_user_personal_chat_messages |
GET /api/uploadposts/telegram/users/{user_id}/personal-chat-messages |
Last messages of a user's personal channel. |
get_telegram_user_profile_audios |
GET /api/uploadposts/telegram/users/{user_id}/profile-audios |
Profile audios of a Telegram user. |
get_telegram_share_theme_backdrops |
GET /api/uploadposts/telegram/share-theme-backdrops |
Backdrops available for the Telegram share screen theme. |
get_telegram_updates_status |
GET /api/uploadposts/telegram/updates |
Whether update receiving is on for the bot. |
Telegram: bot profile, commands and stickers
| Method | Endpoint | What it does |
|---|---|---|
get_telegram_bot_profile |
GET /api/uploadposts/telegram/bot-profile |
Bot name, descriptions, photo, menu button and default administrator rights. |
update_telegram_bot_profile |
PATCH /api/uploadposts/telegram/bot-profile |
Change the bot profile (photo/animation as file or URL, menu_button, default_administrator_rights...). |
get_telegram_bot_commands |
GET /api/uploadposts/telegram/bot-commands |
Bot commands for a scope and language. |
set_telegram_bot_commands |
POST /api/uploadposts/telegram/bot-commands |
Set the bot commands (commands, scope, language_code). |
delete_telegram_bot_commands |
DELETE /api/uploadposts/telegram/bot-commands |
Delete the bot commands of a scope and language. |
get_telegram_sticker_set |
GET /api/uploadposts/telegram/sticker-sets |
Read a sticker set (name) or custom emoji stickers. |
create_telegram_sticker_set |
POST /api/uploadposts/telegram/sticker-sets |
Create a sticker set. |
edit_telegram_sticker_set |
PATCH /api/uploadposts/telegram/sticker-sets |
Edit a sticker set (add, replace, reorder stickers, title, thumbnail, emoji, keywords...). |
delete_telegram_sticker_set |
DELETE /api/uploadposts/telegram/sticker-sets |
Delete a sticker set, or a sticker from it. |
upload_telegram_sticker_file |
POST /api/uploadposts/telegram/sticker-sets/upload |
Upload a sticker file (sticker file or sticker_url, sticker_format, owner_user_id); returns its file_id. |
Telegram: Stars, invoices and gifts
| Method | Endpoint | What it does |
|---|---|---|
get_telegram_stars |
GET /api/uploadposts/telegram/stars |
The bot's Telegram Stars balance. |
get_telegram_star_transactions |
GET /api/uploadposts/telegram/stars/transactions |
The bot's Telegram Stars transactions (offset, limit). |
send_telegram_invoice |
POST /api/uploadposts/telegram/invoices |
Send an invoice to the connected chat or to chat_id (payments go to your bot). |
create_telegram_invoice_link |
POST /api/uploadposts/telegram/invoice-links |
Create an invoice link. |
refund_telegram_star_payment |
POST /api/uploadposts/telegram/stars/refund |
Refund a Telegram Stars payment (user_id, telegram_payment_charge_id). |
edit_telegram_star_subscription |
POST /api/uploadposts/telegram/stars/subscription |
Cancel or re-enable a user's Stars subscription. |
get_telegram_available_gifts |
GET /api/uploadposts/telegram/gifts |
Gifts the bot can send. |
get_telegram_owned_gifts |
GET /api/uploadposts/telegram/gifts/owned |
Gifts owned by a user or a chat. |
get_telegram_unique_gift |
GET /api/uploadposts/telegram/gifts/unique |
A unique gift by name. |
get_telegram_unanswered_payments |
GET /api/uploadposts/telegram/payments/unanswered |
Payment queries that were not answered in time. |
Bluesky: reads
| Method | Endpoint | What it does |
|---|---|---|
get_post_engagement |
GET /api/uploadposts/post-engagement |
Who liked, reposted or quoted a post (type: likes, reposts, quotes; limit, cursor). |
get_bluesky_profiles |
GET /api/uploadposts/bluesky/profile |
One or several Bluesky profiles (actor: handles or DIDs, comma separated, up to 25; without it, the connected account). |
search_bluesky_posts |
GET /api/uploadposts/bluesky/search/posts |
Search Bluesky posts (sort, since, until, author, lang, tag, limit, cursor...). |
search_bluesky_actors |
GET /api/uploadposts/bluesky/search/actors |
Search Bluesky accounts. |
get_bluesky_followers |
GET /api/uploadposts/bluesky/followers |
Followers of an account (actor, or the connected one with user; known=true for followers you follow). |
get_bluesky_follows |
GET /api/uploadposts/bluesky/follows |
Accounts an account follows. |
bluesky_xrpc |
GET /api/uploadposts/bluesky/xrpc/{nsid} |
Read-only gateway to an allow-listed public Bluesky XRPC method (e.g. app.bsky.feed.getAuthorFeed); returns Bluesky's answer untouched. |
get_bluesky_labels |
GET /api/uploadposts/bluesky/labels |
Moderation labels on the account and its posts. |
Bluesky: notifications
| Method | Endpoint | What it does |
|---|---|---|
get_bluesky_notifications |
GET /api/uploadposts/bluesky/notifications |
List notifications (reasons, priority, limit, cursor). |
get_bluesky_unread_count |
GET /api/uploadposts/bluesky/notifications/unread-count |
Unread notification count. |
mark_bluesky_notifications_seen |
POST /api/uploadposts/bluesky/notifications/seen |
Mark notifications as seen (up to seen_at). |
get_bluesky_notification_preferences |
GET /api/uploadposts/bluesky/notification-preferences |
Notification preferences. |
update_bluesky_notification_preferences |
POST /api/uploadposts/bluesky/notification-preferences |
Update notification preferences. |
get_bluesky_activity_subscriptions |
GET /api/uploadposts/bluesky/activity-subscriptions |
Accounts whose activity you are subscribed to. |
set_bluesky_activity_subscription |
POST /api/uploadposts/bluesky/activity-subscriptions |
Subscribe to (or stop) an account's posts and replies. |
Bluesky: profile, settings and drafts
| Method | Endpoint | What it does |
|---|---|---|
get_bluesky_own_profile |
GET /api/uploadposts/bluesky/profile/self |
The connected account's profile record. |
update_bluesky_profile |
POST /api/uploadposts/bluesky/profile/self |
Update the profile (display name, description, avatar/banner files, links, pinned post...). Fields not sent stay as they are. |
get_bluesky_status |
GET /api/uploadposts/bluesky/status |
Read the live status. |
set_bluesky_status |
POST /api/uploadposts/bluesky/status |
Set the live status. |
clear_bluesky_status |
DELETE /api/uploadposts/bluesky/status |
Clear the live status. |
get_bluesky_settings |
GET /api/uploadposts/bluesky/settings |
Chat and discovery settings. |
update_bluesky_settings |
POST /api/uploadposts/bluesky/settings |
Change chat and discovery settings. |
get_bluesky_preferences |
GET /api/uploadposts/bluesky/preferences |
App preferences (content filters, feeds, muted words...). |
update_bluesky_preferences |
PUT /api/uploadposts/bluesky/preferences |
Replace some app preferences. |
list_bluesky_drafts |
GET /api/uploadposts/bluesky/drafts |
List drafts. |
create_bluesky_draft |
POST /api/uploadposts/bluesky/drafts |
Create a draft. |
update_bluesky_draft |
PATCH /api/uploadposts/bluesky/drafts/{draft_id} |
Replace a draft. |
delete_bluesky_draft |
DELETE /api/uploadposts/bluesky/drafts/{draft_id} |
Delete a draft. |
Bluesky: chat
| Method | Endpoint | What it does |
|---|---|---|
get_bluesky_chat_status |
GET /api/uploadposts/dms/bluesky/status |
Chat status of the account. |
get_bluesky_chat_preferences |
GET /api/uploadposts/dms/bluesky/preferences |
DM notification settings. |
update_bluesky_chat_preferences |
POST /api/uploadposts/dms/bluesky/preferences |
Change DM notification settings. |
export_bluesky_chat |
GET /api/uploadposts/dms/bluesky/export |
Export the account's chat history. |
Google Business: posts and reviews
| Method | Endpoint | What it does |
|---|---|---|
list_google_business_posts |
GET /api/uploadposts/google-business/posts |
List the location's posts (location_id, page_size, page_token). Edit them with editPost and delete them with unpublishPost. |
get_google_business_post |
GET /api/uploadposts/google-business/posts/get |
Read one post (post_id or post_name). |
list_google_business_reviews |
GET /api/uploadposts/google-business/reviews |
List reviews (location_id, page_size, page_token, order_by). |
get_google_business_review |
GET /api/uploadposts/google-business/reviews/get |
Read one review (review_name, or review_id + location_id). |
batch_get_google_business_reviews |
GET /api/uploadposts/google-business/reviews/batch |
Reviews of several locations at once (location_ids). |
reply_to_google_business_review |
PUT /api/uploadposts/google-business/reviews/reply |
Reply to a review, or replace the reply (review_name, or review_id + location_id). |
delete_google_business_review_reply |
DELETE /api/uploadposts/google-business/reviews/reply |
Delete the reply to a review. |
Google Business: gallery and performance
| Method | Endpoint | What it does |
|---|---|---|
list_google_business_media |
GET /api/uploadposts/google-business/media |
List the location's gallery. |
get_google_business_media |
GET /api/uploadposts/google-business/media/get |
Read one gallery item. |
upload_google_business_media |
POST /api/uploadposts/google-business/media |
Upload a photo or video to the gallery: file (local path, stream or Buffer) or source_url, plus category, description, media_format. |
update_google_business_media |
PATCH /api/uploadposts/google-business/media |
Change a gallery item's category. |
delete_google_business_media |
DELETE /api/uploadposts/google-business/media |
Delete a gallery item. |
list_google_business_customer_media |
GET /api/uploadposts/google-business/media/customers |
Photos uploaded by customers. |
get_google_business_customer_media |
GET /api/uploadposts/google-business/media/customers/get |
One customer photo. |
get_google_business_performance |
GET /api/uploadposts/google-business/performance |
Daily metrics for any date range (impressions, calls, website clicks, directions...: metrics, start_date, end_date). |
get_google_business_search_keywords |
GET /api/uploadposts/google-business/performance/keywords |
Monthly search keywords that showed the location (start_month, end_month). |
Google Business: location info
| Method | Endpoint | What it does |
|---|---|---|
get_google_business_location_info |
GET /api/uploadposts/google-business/location-info |
Read the location's info (name, address, hours, phones, categories, service area, open status...). |
update_google_business_location_info |
PATCH /api/uploadposts/google-business/location-info |
Edit the location's info. edit_mode: "legacy" (default) or "strict" (dry_run, confirm, include_edit_status); validate_only in both. |
get_google_business_google_updates |
GET /api/uploadposts/google-business/location-info/google-updated |
Changes Google suggested for the location (diff_fields). |
answer_google_business_google_updates |
POST /api/uploadposts/google-business/location-info/google-updates |
Accept or reject Google's suggested changes, field by field. |
get_google_business_location_info_extended |
GET /api/uploadposts/google-business/location-info/extended |
Edit status of each field (experimental). |
list_google_business_locations |
GET /api/uploadposts/google-business/locations/list |
List locations with filters (account, filter, order_by, read_mask, page_size, page_token). |
get_google_business_pinned_location |
GET /api/uploadposts/users/google-business-location |
Locations available to a profile and the one pinned for its uploads. |
pin_google_business_location |
POST /api/uploadposts/users/google-business-location |
Pin the location a profile publishes to (instead of passing gbpLocationId on every upload). |
clear_google_business_location_pin |
DELETE /api/uploadposts/users/google-business-location |
Clear the pinned location. |
Google Business: catalogs, attributes, Place Actions, menus, services and lodging
| Method | Endpoint | What it does |
|---|---|---|
search_google_business_categories |
GET /api/uploadposts/google-business/categories |
Search categories (region_code, language_code, query). |
batch_get_google_business_categories |
GET /api/uploadposts/google-business/categories/batch |
Category details: service types and more-hours types (names). |
search_google_business_chains |
GET /api/uploadposts/google-business/chains |
Search chains (name). |
get_google_business_chain |
GET /api/uploadposts/google-business/chains/get |
One chain (chain). |
search_google_business_google_locations |
POST /api/uploadposts/google-business/google-locations/search |
Is the business already on Google? Search Google's listings. |
get_google_business_recommended_locations |
GET /api/uploadposts/google-business/google-locations/recommended |
Locations Google recommends for the account. |
report_google_business_google_location |
POST /api/uploadposts/google-business/google-locations/report |
Report a wrong listing to Google. |
get_google_business_available_attributes |
GET /api/uploadposts/google-business/attributes/available |
Attributes the location can use. |
get_google_business_attributes |
GET /api/uploadposts/google-business/attributes |
Current attributes of the location. |
update_google_business_attributes |
PATCH /api/uploadposts/google-business/attributes |
Update attributes. |
get_google_business_attributes_google_updated |
GET /api/uploadposts/google-business/attributes/google-updated |
Attributes as Google shows them. |
get_google_business_attributes_extended |
GET /api/uploadposts/google-business/attributes/extended |
Attributes with their edit status (experimental). |
get_google_business_place_action_types |
GET /api/uploadposts/google-business/place-actions/types |
Place Action types (booking, ordering, shopping links...) the location can use. |
list_google_business_place_actions |
GET /api/uploadposts/google-business/place-actions |
List Place Action links. |
get_google_business_place_action |
GET /api/uploadposts/google-business/place-actions/get |
Read one Place Action link (link). |
create_google_business_place_action |
POST /api/uploadposts/google-business/place-actions |
Create a Place Action link. |
update_google_business_place_action |
PATCH /api/uploadposts/google-business/place-actions |
Edit or switch off a Place Action link. |
delete_google_business_place_action |
DELETE /api/uploadposts/google-business/place-actions |
Delete a Place Action link. |
get_google_business_food_menus |
GET /api/uploadposts/google-business/food-menus |
Food menus of the location. |
update_google_business_food_menus |
PUT /api/uploadposts/google-business/food-menus |
Replace the food menus. |
get_google_business_services |
GET /api/uploadposts/google-business/services |
Services of the location. |
update_google_business_services |
PUT /api/uploadposts/google-business/services |
Replace the services. |
get_google_business_lodging |
GET /api/uploadposts/google-business/lodging |
Lodging data of a hotel (read_mask). |
update_google_business_lodging |
PATCH /api/uploadposts/google-business/lodging |
Update lodging data. |
get_google_business_lodging_google_updated |
GET /api/uploadposts/google-business/lodging/google-updated |
Lodging data as Google shows it. |
Google Business: accounts and verification (reads)
| Method | Endpoint | What it does |
|---|---|---|
list_google_business_accounts |
GET /api/uploadposts/google-business/accounts |
Google Business accounts and location groups (type). |
get_google_business_account |
GET /api/uploadposts/google-business/accounts/get |
Read one account (account). |
create_google_business_account |
POST /api/uploadposts/google-business/accounts |
Create a location group or user group (type, account_name, confirm). |
list_google_business_admins |
GET /api/uploadposts/google-business/admins |
Admins of an account or a location (scope, location_id). |
list_google_business_invitations |
GET /api/uploadposts/google-business/invitations |
Pending invitations of an account. |
get_google_business_verification_state |
GET /api/uploadposts/google-business/verification/state |
Whether the location is verified and in good standing. |
get_google_business_verification_options |
POST /api/uploadposts/google-business/verification/options |
Verification methods available for the location. |
list_google_business_verifications |
GET /api/uploadposts/google-business/verifications |
Past verifications of the location. |
AutoDM monitors (one post)
A monitor answers every new comment on one post: a private DM on Instagram, a public reply on TikTok, YouTube, Facebook, Threads and Bluesky. Monitors stop after 15 days and a profile can create 2 per day (account-wide Instagram rules are below, in AutoDM rules).
monitor = client.start_autodm("my-profile", "Thanks! Check your DMs",
post_url="https://www.instagram.com/p/XXXX/", trigger_keywords=["info"])
client.get_autodm_status(include_inactive=True)
client.get_autodm_logs(monitor["monitor_id"])
client.pause_autodm(monitor["monitor_id"]) # also resume_autodm, stop_autodm, delete_autodm
What a TikTok connection can do (capabilities)
Not every TikTok connection can do the same things. client.list_users()
(GET /api/uploadposts/users) returns a capabilities array on each profile's
TikTok account; check it before offering a feature.
| Capability | What it unlocks |
|---|---|
music |
tiktok_music_id and the volume/trim fields, plus get_tiktok_trending_music() and search_tiktok_music() |
location |
tiktok_location_id / tiktok_location_name, plus get_tiktok_locations() |
cover_image |
tiktok_cover_image_url |
cover_timestamp |
cover_timestamp |
draft |
tiktok_upload_to_draft or post_mode="MEDIA_UPLOAD" (same draft) |
video_privacy |
privacy_level on video |
photo_privacy |
privacy_level on photo posts |
profile_analytics |
get_audience() and get_suggestions(type="hashtags") with platform="tiktok" |
comments |
Comments on TikTok: get_post_comments() (top-level and replies), create_comment(), delete_comment(), comment_action() and tiktok_first_comment |
trend_search |
get_suggestions(type="keywords") with platform="tiktok" |
commentsandtrend_searchneed the account to be reconnected. TikTok grants them at connect time, so an account linked before they existed keeps working for everything else but will not list them — reconnect it from Manage Users to enable them.
If a connection lacks a capability the upload field is simply ignored: the post
still publishes and the response carries a per-field warnings string. The
methods above answer with an error asking for a reconnection.
TikTok music, location, cover and drafts
Needs the
music,location,cover_imageordraftcapability — see What a TikTok connection can do.
# 1. Pick a track and a place
tracks = client.get_tiktok_trending_music("my-profile", country_code="ES")["tracks"]
# ...or find one by name. TikTok has no music search endpoint, so this searches
# the trending charts Upload-Post caches, not TikTok's whole catalogue.
tracks = client.search_tiktok_music("my-profile", q="bossa", country_code="ES")["tracks"]
places = client.get_tiktok_locations("my-profile", "Madrid")["locations"]
# 2. Publish with them
client.upload_video(
"video.mp4",
title="Shot in Madrid",
user="my-profile",
platforms=["tiktok"],
tiktok_music_id=tracks[0]["id"],
tiktok_music_volume=70, # 0-100, defaults to 50 when music is set
tiktok_music_start=0, # ms
tiktok_music_end=15000, # ms
tiktok_original_sound_volume=30, # 0-100, defaults to 50 so the original audio is not muted
tiktok_location_id=places[0]["location_id"],
tiktok_location_name=places[0]["location_name"], # required together with the id
tiktok_cover_image_url="https://example.com/cover.jpg",
tiktok_is_ai_generated=False,
tiktok_upload_to_draft=False, # same draft as post_mode="MEDIA_UPLOAD"
)
TikTok music, location, cover and draft options
| Option | Type | Capability | Notes |
|---|---|---|---|
tiktok_music_id |
str | music |
Video + photos. The track id from get_tiktok_trending_music() or search_tiktok_music() (not commercial_music_id) |
tiktok_music_volume |
int | music |
Video only. 0-100, defaults to 50 when music is set |
tiktok_music_start |
int | music |
Video only. Music start offset in ms |
tiktok_music_end |
int | music |
Video only. Music end offset in ms |
tiktok_original_sound_volume |
int | music |
Video only. 0-100, defaults to 50 when music is set, so the original audio is not muted |
tiktok_location_id |
str | location |
Video + photos. location_id from get_tiktok_locations() |
tiktok_location_name |
str | location |
Required whenever tiktok_location_id is set |
tiktok_cover_image_url |
str | cover_image |
Video only. Custom cover image URL |
tiktok_is_ai_generated |
bool | — | Video + photos. AI-generated content disclosure (aliases: is_ai_generated) |
tiktok_upload_to_draft |
bool | draft |
Video + photos. Same draft as post_mode="MEDIA_UPLOAD" (aliases: upload_to_draft, is_draft). TikTok ignores the rest of the post settings |
tiktok_is_ads_only |
bool | — | Video. Only show in ads (alias: is_ads_only) |
tiktok_tto_invite_link |
str | — | Video. TikTok One invite link; needs branded content (alias: tto_invite_link) |
photo_cover_index |
int | — | Cover photo index for photo posts (0-based) |
privacy_level |
str | photo_privacy / video_privacy |
Accepted on video and photo posts alike; which values the account may use is decided by TikTok, see the note below |
post_mode |
str | draft |
DIRECT_POST or MEDIA_UPLOAD. MEDIA_UPLOAD is the same draft as tiktok_upload_to_draft=True |
Platform-Specific Options
TikTok (Video)
disable_duet- Disable duetdisable_comment- Disable commentsdisable_stitch- Disable stitchcover_timestamp- Timestamp in ms for coveris_aigc- AI-generated content flagpost_mode- DIRECT_POST or MEDIA_UPLOAD.MEDIA_UPLOADis the same draft astiktok_upload_to_draft=Truebrand_content_toggle- Branded content togglebrand_organic_toggle- Brand organic toggletiktok_is_ads_only- Only show the video in ads (alias:is_ads_only)tiktok_tto_invite_link- TikTok One invite link; needs branded content (alias:tto_invite_link)
TikTok particularity:
privacy_levelworks on video and photo posts alike, but TikTok decides per account which values are available. A private account, for example, is offeredFOLLOWER_OF_CREATOR,MUTUAL_FOLLOW_FRIENDSandSELF_ONLY, with noPUBLIC_TO_EVERYONE; asking for one the account does not have fails witherror_code="tiktok_privacy_unavailable"and an error listing the ones it does have. Omit it on video and TikTok applies the account's own default; on photo posts it defaults toPUBLIC_TO_EVERYONE. To offer only the values that will actually work, ask the account withclient.get_tiktok_publishing_settings(profile)and readprivacy_level_options.
See TikTok music, location, cover and drafts for the music, location, cover and draft options.
TikTok (Photos)
privacy_level- PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLYpost_mode- DIRECT_POST or MEDIA_UPLOAD.MEDIA_UPLOADis the same draft astiktok_upload_to_draft=Trueauto_add_music- Auto add musicphoto_cover_index- Index of photo for cover (0-based)disable_comment- Disable commentstiktok_music_id- Commercial Music Library track idtiktok_location_id/tiktok_location_name- Location tag, both required togethertiktok_is_ai_generated- AI-generated content disclosuretiktok_upload_to_draft- Same draft aspost_mode="MEDIA_UPLOAD"(aliases:upload_to_draft,is_draft)
TikTok's photo contract takes the music track id alone:
tiktok_music_volume,tiktok_music_start,tiktok_music_end,tiktok_original_sound_volumeandtiktok_cover_image_urlare video-only.post_mode="MEDIA_UPLOAD"andtiktok_upload_to_draft=Trueare aliases of the same draft.
media_type- REELS, STORIES, IMAGEshare_to_feed- Share to feed (for Reels/Stories)collaborators- Comma-separated collaborator usernamescover_url- Custom cover URLaudio_name- Audio track nameuser_tags- Comma-separated user tagslocation_id- Location IDthumb_offset- Thumbnail offsetinstagram_alt_text- Alt text (string, or JSON list / one per carousel item)
YouTube
tags- List or comma-separated tagscategoryId- Category ID (default: "22" People & Blogs)privacyStatus- public, unlisted, privateembeddable- Allow embeddinglicense- youtube, creativeCommonpublicStatsViewable- Show public statsthumbnail_url- Custom thumbnail URLselfDeclaredMadeForKids- Made for kids (COPPA)containsSyntheticMedia- AI/synthetic content flagdefaultLanguage- Title/description language (BCP-47)defaultAudioLanguage- Audio language (BCP-47)allowedCountries/blockedCountries- Country restrictionshasPaidProductPlacement- Paid placement flagrecordingDate- Recording date (ISO 8601)youtube_playlist_id- Playlist ID (single string, list, or comma-separated) to add the uploaded video to after publishingyoutube_notify_subscribers- Notify subscribers (defaulttrue; sendfalseto skip)youtube_publish_at- RFC3339 time; uploads as private and schedules on YouTube
visibility/linkedin_visibility- PUBLIC, CONNECTIONS, LOGGED_IN, CONTAINERtarget_linkedin_page_id- Page ID for organization postslinkedin_alt_text- Alt text per image (string, JSON list, or repeated)linkedin_disable_reshare- Disable reshare by otherslinkedin_link_title/linkedin_link_description/linkedin_thumbnail_alt_text- Article/link-share overrideslinkedin_target_geo_locations/linkedin_target_industries/linkedin_target_seniorities/linkedin_target_job_functions/linkedin_target_staff_count_ranges/linkedin_target_interface_locales/linkedin_target_degrees/linkedin_target_fields_of_study/linkedin_target_organizations- Page targeting (needstarget_linkedin_page_id)linkedin_target_entities- Raw targeting JSON instead of the fields abovelinkedin_target_check_audience- Reject if LinkedIn reports fewer than 300 followers in the segmentlinkedin_subtitles/linkedin_subtitles_url/linkedin_subtitles_text- English SRT captions on video
facebook_page_id- Facebook Page ID (required)video_state- PUBLISHED, DRAFTfacebook_media_type- REELS, STORIES, or VIDEO (normal page video)thumbnail_url- Thumbnail URL for normal page videos (only whenfacebook_media_typeis VIDEO)facebook_link_url- URL for text postsfacebook_alt_text- Alt text per photo (string,facebook_alt_text[], or JSON array)facebook_place_id- Place id on feed/photos/videos/reelsfacebook_targeting/facebook_feed_targeting- JSON audience objectsfacebook_call_to_action/facebook_child_attachments/facebook_multi_share_end_card- Link post CTA and carouselfacebook_is_ai_generated- AI-generated flag on Reelsfacebook_collaborators- Page ids to invite on Reelsfacebook_unpublished_content_type- DRAFT / INLINE_CREATED / ADS_POST on page video (SCHEDULEDis rejected; usescheduled_date)facebook_no_story/facebook_secret- Page video flags
pinterest_board_id- Board IDpinterest_link- Destination linkpinterest_alt_text- Alt text for photospinterest_cover_image_url- Cover image URL (video)pinterest_cover_image_key_frame_time- Key frame time in seconds (values larger than the video duration are treated as milliseconds)pinterest_board_section_id- Board section idpinterest_ai_disclosures-AI_MODIFIEDand/orSYNTHETIC_PERFORMERpinterest_carousel_titles/pinterest_carousel_descriptions/pinterest_carousel_links- Per-slide carousel fields (2–5 photos)pinterest_carousel_index- 0-based cover slide
X (Twitter)
reply_settings- everyone, following, mentionedUsers, subscribers, verifiednullcast- Promoted-only posttagged_user_ids- User IDs to tagplace_id/geo_place_id- Location place IDquote_tweet_id- Tweet ID to quotepoll_options- Poll options (2-4)poll_duration- Poll duration in minutes (5-10080)for_super_followers_only- Exclusive for super followerscommunity_id- Community IDshare_with_followers- Share community post with followerscard_uri- Card URI for Twitter Cardsx_long_text_as_post- Post long text as single postx_thread_image_layout- Comma-separated image layout for thread (e.g. "4,4" or "2,3,1"). Each value 1-4, total must equal image count. Auto-chunks into groups of 4 when >4 images.x_alt_text- Alt text (string,x_alt_text[], or JSON array; ≤1000 chars)x_subtitles/x_subtitles_url/x_subtitles_language/x_subtitles_name- Video SRT captionsx_paid_partnership- Paid partnership flag on the first postx_article_title/x_article_body/x_article_content_state/x_article_draft/x_article_cover_media- X Articles (text; Premium). Articles have two heading levels: a### Headingin the body, or aheader-threeblock inx_article_content_state, is published asheader-two
Threads
threads_long_text_as_post- Post long text as single post (vs thread). Over 500 UTF-8 bytes this sends an official long post instead of truncating.threads_thread_media_layout- Comma-separated list of how many media items to include in each Threads post (e.g. "5,5" or "3,4,3"). Each value 0-20, total must equal media count. Auto-chunks into groups of 20 when >20 items.threads_topic_tag- Topic tag for the Threads post (1-50 characters, no periods or ampersands). One tag per post. Helps increase reach.threads_reply_control- Who can reply:everyone,accounts_you_follow,mentioned_only,parent_post_author_only,followers_onlythreads_alt_text- Alt text per image/video (threads_alt_text[])threads_reply_to_id/threads_quote_post_id- Reply or quotethreads_link_attachment- Force link preview (text)threads_poll_options- 2–4 poll options (text)threads_auto_publish_text- Skip the second publish call on text posts
Reddit uploads currently return error_code=reddit_unavailable until the Reddit app is restored.
subreddit- Subreddit name (without r/)flair_id- Flair template IDreddit_nsfw/reddit_spoiler/reddit_resubmit/reddit_send_replies- Booleansreddit_flair_text- Custom text for editable flairsreddit_gallery_captions/reddit_gallery_urls- Per-image gallery caption and outbound URL
Google Business
gbp_location_id- Location, e.g."accounts/123/locations/456"(list them withget_google_business_locations). Required when the account has more than one location; the API only auto-selects when exactly one exists.gbp_post_type-MEDIA,PHOTOorGALLERYto publish into the location's photo gallery instead of creating a Local Post. Any other value, or omitting it, keeps the Local Post behaviour.gbp_media_category- Gallery category, defaultADDITIONAL. One ofCOVER,PROFILE,LOGO,EXTERIOR,INTERIOR,PRODUCT,AT_WORK,FOOD_AND_DRINK,MENU,COMMON_AREA,ROOMS,TEAMS,ADDITIONAL.gbp_topic_type- STANDARD, EVENT or OFFERgbp_media_url/gbp_media_format- Media attached to the postgbp_cta_type/gbp_cta_url- Call-to-action buttongbp_event_title/gbp_event_start_date/gbp_event_start_time/gbp_event_end_date/gbp_event_end_time- Used withgbp_topic_type="EVENT"gbp_offer_coupon/gbp_offer_redeem_url/gbp_offer_terms- Used withgbp_topic_type="OFFER"gbp_coupon_code/gbp_redeem_url/gbp_terms- Aliases of the offer fields above (legacy names still win if both are sent)gbp_language_code- BCP-47 language (defaulten)gbp_recurrence(DAILY,WEEKLY,MONTHLY) withgbp_recurrence_days/gbp_recurrence_day_of_month/gbp_recurrence_week_occurrence/gbp_recurrence_end- Recurring EVENT and OFFER postsgbp_scheduled_time- Google's own scheduling (RFC 3339 with time zone)gbp_multi_media- With a list ingbp_media_url(sent asgbp_media_url[]): several photos, max 10gbp_alert_type- For ALERT posts (COVID_19)gbp_upload_to_gallery- Same asgbp_post_type="MEDIA"
List, read, edit and delete the posts afterwards with list_google_business_posts,
get_google_business_post, edit_post and unpublish_post, or pin the location a
profile publishes to with pin_google_business_location.
locations = client.get_google_business_locations("my-profile")
# Publish a photo straight into the location's gallery
client.upload_photos(
["storefront.jpg"],
user="my-profile",
platforms=["google_business"],
gbp_location_id=locations["locations"][0]["name"],
gbp_post_type="GALLERY",
gbp_media_category="EXTERIOR",
)
Bluesky
bluesky_link_url- External embed link preview (text)bluesky_alt_text- Alt text per image/video (JSON array,||-separated, or string)bluesky_langs- Comma list, max 3 BCP-47 codesbluesky_labels-porn,sexual,nudity,graphic-mediabluesky_gallery- Publish up to 10 images as a gallery (falsekeeps the first 4). With more than 10, the first 10 are published and the response carries awarningsentrybluesky_threadgate/bluesky_reply_settings- Who can replybluesky_postgate/bluesky_quote_settings-disable_quotesto block quotesbluesky_quote_uri/bluesky_quote_id/bluesky_quote_url- Quote another postbluesky_tags- Up to 8 extra hashtags stored on the post, not shown in the textbluesky_created_at- Date Bluesky shows the post with (ISO 8601 with timezone, not in the future)bluesky_thread_overflow- Text over 300 characters goes on as replies instead of being cutbluesky_gif_as_video- A single animated GIF published as a looping videobluesky_captions- Video subtitles:[{"lang": "es", "url": "https://.../es.vtt"}](WebVTT)bluesky_video_presentation-defaultorgif
Discord
discord_thread_id/discord_thread_name/discord_applied_tags- Thread or forum postdiscord_embeds/discord_poll/discord_allowed_mentions- JSONdiscord_username/discord_avatar_url- Per-post webhook identitydiscord_alt_text/discord_flags/discord_tts/discord_max_file_mb
Telegram
telegram_parse_mode-MarkdownV2orHTMLtelegram_message_thread_id- Forum topictelegram_disable_notification/telegram_protect_content/telegram_has_spoiler/telegram_pintelegram_link_preview/telegram_reply_markup/telegram_as_documenttelegram_caption_overflow-truncate(default) orsplittelegram_media_urls- Comma-separated public URLs for a mixed albumtelegram_title/telegram_first_comment- Telegram text and first commenttelegram_poll/telegram_location/telegram_venue/telegram_contact/telegram_dice/telegram_game_short_name- Send a poll, a (live) location, a venue, a contact or a dice instead of a plain message (Telegram's JSON shapes)telegram_pin_notify- Notify the members when pinningtelegram_reply_to_message_id/telegram_reply_quote/telegram_reply_parameters- Reply to a messagetelegram_link_preview_options/telegram_entities/telegram_caption_entities/telegram_show_caption_above_media- Formattingtelegram_first_comment_as_reply- The first comment as a reply to the post (defaultTrue)telegram_direct_messages_topic_id/telegram_suggested_post_parameters/telegram_ephemeral_message_parameters/telegram_message_effect_idtelegram_send_as(animation,video_note,live_photo,document,audio,voice...) withtelegram_performer/telegram_title_audio/telegram_duration/telegram_length/telegram_emoji/telegram_live_photo_phototelegram_paid_star_count/telegram_paid_payload- Paid media unlocked with Telegram Starstelegram_cover/telegram_thumbnail(local file or URL) /telegram_start_timestamp/telegram_send_by_url/telegram_disable_content_type_detection
Mastodon
mastodon_visibility/mastodon_sensitive/mastodon_spoiler_text/mastodon_languagemastodon_alt_text-|-separated for albumsmastodon_poll_options/mastodon_poll_expires_in/mastodon_poll_multiplemastodon_scheduled_at- ISO 8601, at least 5 minutes ahead
WordPress
wordpress_status/wordpress_date-publish,draft,pending,future(daterequired forfuture)wordpress_categories/wordpress_tags/wordpress_excerpt/wordpress_slugwordpress_alt_text/wordpress_media_caption/wordpress_block_format
Lemmy
lemmy_url/lemmy_community/lemmy_nsfw/lemmy_language_id/lemmy_alt_text
Slack
slack_markdown/slack_mrkdwn/slack_blocks/slack_alt_textslack_first_comment_mode-separate(default) orinline
Nostr
nostr_kind-1default,20picture,22short video,34235video,30023long-formnostr_long_form- Shorthand for kind 30023
Dev.to
devto_tags/devto_canonical_url/devto_description/devto_main_image/devto_series/devto_published
Hashnode
hashnode_body/content- Article bodyhashnode_tags/hashnode_original_article_url/hashnode_subtitle/hashnode_cover_image_url/hashnode_draft
Whop
whop_body/whop_pinned/whop_is_mention/whop_paywall_amount/whop_paywall_currency/whop_attachment_ids
Listmonk
listmonk_content_type-richtext(default),markdown,html,plainlistmonk_send_at/listmonk_lists/listmonk_template_id/listmonk_media_ids
Common Options
These options work across all upload methods:
| Option | Description |
|---|---|
title |
Post title/caption (required) |
user |
Profile name (required) |
platforms |
Target platforms list (required) |
first_comment |
First comment to post |
tiktok_first_comment |
First comment for TikTok only (needs the comments capability) |
alt_text |
Alt text for accessibility |
scheduled_date |
ISO date for scheduling |
timezone |
Timezone for scheduled date |
add_to_queue |
Add to posting queue |
max_posts_per_slot |
Max posts per queue slot (overrides profile setting) |
async_upload |
Process asynchronously (default: True) |
paid_partnership |
Sponsored post. Mapped to each network's native label (TikTok brand_content_toggle, YouTube hasPaidProductPlacement, X paid_partnership); Facebook and Pinterest also need facebook_sponsor_id / pinterest_sponsor_id. Networks without a label publish without it, with a warning. A network-specific field wins. TikTok's own switch: disclose_commercial with your_brand / branded_content |
Error Handling
from upload_post import UploadPostClient, UploadPostError
client = UploadPostClient("YOUR_API_KEY")
try:
response = client.upload_video("video.mp4", **options)
print("Upload successful:", response)
except UploadPostError as e:
print("Upload failed:", str(e))
print(e.status_code) # HTTP status, or None if no answer arrived
print(e.error_code) # stable code, e.g. "bluesky_dm_scope_missing", "TEAM_SEAT_SUSPENDED"
print(e.response) # decoded JSON body of the error
print(e.retry_after) # Retry-After seconds, when the API sent it
Links
License
MIT
Metadata
Release files for upload-post 2.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| upload_post-2.16.0.tar.gz | 122.8 kB | With provenance | Details for upload_post-2.16.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| upload_post-2.16.0-py3-none-any.whl | Python 3 | none | any | Details for upload_post-2.16.0-py3-none-any.whl |
Total release size: 188.1 kB
Release files / upload_post-2.16.0.tar.gz
| Download URL | upload_post-2.16.0.tar.gz |
|---|---|
| Size | 122.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49c1b0ffcd30ab84cdf78f9714397527421d481676a802cdb8d00639ef153f4c
|
|
BLAKE2b-256 checksum How to use checksums |
3de88758242239e7de5689505898fe8d176348445e5116ab6211ead5fb4c9b91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / upload_post-2.16.0-py3-none-any.whl
| Download URL | upload_post-2.16.0-py3-none-any.whl |
|---|---|
| Size | 65.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eb00de799958f73ae255ae0a28d80e685746efbc632ce9b4f64d169526938cf6
|
|
BLAKE2b-256 checksum How to use checksums |
e11d18af304a409e45d9679b22f03a270f48547ae1e7ae9ad6a59480445d5b2d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for upload-post 2.16.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for upload_post-2.16.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.