Description

n8n-nodes-upload-post

This is an n8n community node package for Upload Post. It allows you to automate uploading photos, videos, and text posts to various social media platforms supported by the Upload Post API.

n8n is a fair-code licensed workflow automation tool.

Installation

Follow the n8n community node installation guide to install this node.

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter n8n-nodes-upload-post in Enter npm package name.
4. Agree to the risks of using community nodes.
5. Select Install.

After installing the node, you can use it in your n8n workflows.

Credentials

To use this node, you need to configure the Upload Post API credentials:

1. Create an API key from your Upload Post dashboard.
2. In n8n, go to Credentials > New.
3. Search for Upload Post API and select it.
4. Enter a Credential Name.
5. Paste your Upload Post API key into the API Key field.
6. Select Save.

Operations

The node provides the following operations grouped for clarity:

Upload Actions

• Upload Photo(s): Upload one or more photos to supported platforms.

– Supports file uploads and photo URLs (comma-separated list).
– Common parameters: User Identifier, Platform Names or IDs, Title / Main Content, Description (optional), Photos (Files or URLs), Scheduled Date (optional).
– Title/Description overrides per platform: instagramtitle, facebooktitle, tiktoktitle, linkedintitle, xtitle, youtubetitle, pinteresttitle, threadstitle.
– Platform-specific parameters available for: Discord, Facebook, Instagram, LinkedIn, Pinterest, Telegram, TikTok, X (Twitter).
– Pinterest: Requires Board selection via dynamic selector.
– Instagram: Media Type (Image/Stories), TikTok: Auto-add music, disable comments, brand content toggles.
– Facebook: Page selection via dynamic selector.
– LinkedIn: Visibility settings (Photos only), Page selection via dynamic selector.
– X (Twitter): Tagged user IDs, reply settings, geo place ID.

• Upload Video: Upload a single video to supported platforms.

– Supports file uploads and video URLs.
– Common parameters: User Identifier, Platform Names or IDs, Title / Main Content, Description (optional), Video (File or URL), Scheduled Date (optional).
– Title/Description overrides per platform: instagramtitle, facebooktitle, tiktoktitle, linkedintitle, xtitle, youtubetitle, pinterest_title.
– Platform-specific parameters available for: Discord, Facebook, Instagram, LinkedIn, Pinterest, Telegram, Threads, TikTok, X (Twitter), YouTube.
– YouTube: Custom thumbnail (URL/binary), tags, category, privacy, embeddable, license, public stats, made for kids, synthetic media declaration, geo-restrictions, paid product placement, recording date, default language/audio language.
– Facebook: Page selection, video state (Published/Draft), media type (Reels/Stories).
– Instagram: Media type (Reels/Stories), share to feed, collaborators, cover URL, audio name, user tags, location ID, thumb offset.
– TikTok: Privacy level, disable duet/stitch/comments, cover timestamp, brand content toggles, AI-generated content flag, post mode.
– LinkedIn: Visibility settings, Page selection, video description.
– Pinterest: Board selection, cover image options (URL/base64/keyframe).
– X (Twitter): Tagged user IDs, reply settings, nullcast, place ID, long text handling.

• Upload Text: Upload a text-based post to supported platforms.

– Common parameters: User Identifier, Platform Names or IDs, Title / Main Content (used as post content), Scheduled Date (optional).
– Platform-specific parameters available for: Discord, Facebook, LinkedIn, Reddit, Telegram, Threads, X (Twitter).
– Facebook: Page selection, link URL for preview.
– LinkedIn: Page selection (“Me” for personal profile).
– X (Twitter): Reply settings, poll options (2-4 options, 5-10080 min duration), post URL, quote tweet ID, geo place ID, super followers exclusivity, community ID, sharing options, direct message deep link, card URI, long text handling.
– Threads: Long text as single post option.
– Reddit: Subreddit selection, flair ID.

Status & History Actions

• Get Upload Status: Check the status/result of an async upload by request_id.

– Parameters: Request ID.

• Get Upload History: List past uploads.

– Parameters: Page (default 1), Limit (default 20). Limit can be 20, 50, or 100.

• Get Analytics: Retrieve aggregated profile analytics.

– Parameters: Profile Username, Platforms (required — at least one), Facebook Page ID (required when Facebook is selected), LinkedIn Page URN (optional).
– Supported: Facebook, Instagram, LinkedIn, Pinterest, Reddit, Threads, TikTok, X, YouTube. Analytics are not available for Bluesky, Discord, Google Business or Telegram.

• Get Post Analytics: Per-post metrics for an upload, by request_id.

– Parameters: Request ID, Platform (optional filter).
– On TikTok, postmetrics also carries retention, impressionsources, audiencetypes, newfollowers, reach and the watch times.

• Get Post Analytics by Platform ID: Per-post metrics for a post published outside Upload-Post.

– Parameters: Platform Post ID, Platform, Profile Username.

• Get Cached Post Analytics: Replays per-post metrics already fetched, instead of querying the platforms again, so it is not subject to the live analytics rate limit (100 requests / 5 minutes). 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.

– Parameters: Profile Username (required), Platform (optional filter), Limit (default 50, max 200), Cursor, Since / Until (YYYY-MM-DD, defaults to the last 30 days).
– Values are only as fresh as your last live read — check captured_at on each post. Use Get Post Analytics for a just-published post and this operation for bulk or historical reads.
– Paginate by passing the nextcursor from the previous response as Cursor while hasmore is true.
– Supported: Facebook, Instagram, LinkedIn, Pinterest, Reddit, Threads, TikTok, YouTube. X (Twitter) is not cached.

• Get Total Impressions: Impressions aggregated across connected platforms.

– Parameters: Profile Username, Period or Start/End Date, Platforms, Breakdown.

• Get Platform Metrics: Lists which metrics each platform exposes.
• Get Reddit Detailed Posts: Detailed Reddit posts with full media information.

– Parameters: Profile Username.

Scheduled Posts

• List Scheduled Posts: Lists future scheduled jobs.
• Cancel Scheduled Post: Cancels a scheduled job by its Job ID.
• Edit Scheduled Post: Updates a scheduled job (e.g., new scheduled date/time).

– Tip: You can schedule any Upload action by providing the Scheduled Date during upload.

Platform Selectors (Dynamic)

• Facebook Pages: Dynamic picker for Facebook pages, or enter ID via expression. Required for all Facebook operations.
• LinkedIn Pages: Dynamic picker for organization pages with “Me (Personal Profile)” option, or enter ID via expression.
• Pinterest Boards: Dynamic picker for Pinterest boards, or enter ID via expression. Required for all Pinterest operations.

User Actions (incl. JWT for custom platform integration)

• ⚠️ JWT endpoints are only needed if you integrate Upload-Post into your own platform and want end-users to link their social accounts via your UI.
• List Users: Retrieve Upload-Post profiles created under your API key.
• Create User: Create a new user profile.

– Parameters: New User Identifier (username).

• Delete User: Delete an existing user profile.

– Parameters: Username to delete.

• Generate JWT (for platform integration): Generate a connection URL (JWT) for a given profile so the user can link social accounts.

– Parameters: User Identifier, optional redirect URL, logo image URL, redirect button text, platform restrictions, calendar options, connect title/description, language, UI labels.
– Language: forces the connection page language. Supported: English, Spanish, German, French, Portuguese, Polish, Turkish. Leave on Auto-Detect to use the visitor’s browser language (falls back to English).
– UI Labels: white-label overrides for individual connection page texts, as key/value pairs (sent as uilabels). The key is an i18n dot-path such as connect.connectButton, the value the replacement string. The API accepts up to 100 entries, keys matching ^[a-zA-Z0-9.]+$ and values of up to 300 characters, and rejects the request otherwise.

• Validate JWT (for platform integration): Validate a connection token from your backend.

– Parameters: JWT token (password field).
– The API response is returned as-is; its profile object also carries the ui_labels map configured for that profile.

Comment Actions

The comment endpoints are shaped like the rest of the API: one endpoint per question, with a platform parameter that says which connected network is being asked. There is no endpoint per social network.

• Get Post Comments: Comments on a post from the network given by Platform (Instagram, Facebook, YouTube, LinkedIn or TikTok).

– Parameters: User Identifier, Platform, Post ID or URL, Comment ID (optional).
– Instagram and Facebook accept the media ID or the post URL, YouTube the video ID, LinkedIn the post URN, TikTok the video ID. TikTok has no URL lookup, so pasting a URL fails with a descriptive error instead of an upstream one.
– Fill Comment ID to get the replies to that comment instead of the top-level comments of the post. It is the same question with one parameter more, not a separate operation.

• Comment Action: Moderate one comment — hide, unhide, like, unlike, pin or unpin it.

– Parameters: User Identifier, Platform, Comment ID, Action, Post ID (shown only when it is needed).
– Each action carries its own inverse, so there is no separate toggle: hide/unhide, like/unlike, pin/unpin.
– Post ID is required for hide, unhide, pin and unpin, and is never sent for like/unlike — the API rejects a like that carries a post. The node checks it before the request leaves n8n.
– TikTok is the network that answers this today, and its profile needs the comments capability (see the capabilities array returned by List Users); an account connected before that capability existed has to reconnect TikTok.

• Private Reply to Comment: DM the author of a comment. Instagram only.
• Public Reply to Comment: Public reply under the comment. Instagram only.

Insight Actions

Two more questions with a platform parameter, not two TikTok endpoints. A network that cannot answer a question replies with platformnotsupported and the list of the ones that can; today that network is TikTok, whose profile needs the profile_analytics capability (see the capabilities array returned by List Users).

• Get Audience: Who follows the profile and when they are around — audience countries, cities, age brackets and genders, followers online per hour, daily followers gained and lost, profile actions and the bio.

– Parameters: User Identifier, Platform, Start Date, End Date, Benchmark Category (all optional except the first two).
– Dates are YYYY-MM-DD. The window is clamped by the server: 60 days at most, and End Date always below today. A wider range is trimmed, not rejected, so the node sends it as typed.
– Filling Benchmark Category adds a benchmark object with that niche’s averages (comments, engagement rate, follower count and growth, likes, shares, video count and views) next to the account’s own numbers. The 25 accepted values come back in benchmark_categories on every response, so filling a picker needs no extra call.
– Use this to know who the audience is and when to post; use Get Post Analytics for how a given post did.

• Get Suggestions: What to write about — hashtags or the searches people run around a seed word.

– Parameters: User Identifier, Platform, Type (hashtags / keywords), Query, Country Code, Language.
– Type = hashtags answers with hashtags: [{ name, view_count }]; Type = keywords answers with keywords: [...]. One endpoint, told apart by type, not by operation.

Refer to the Upload Post API Documentation for detailed information on parameters and platform requirements.

Waiting for asynchronous uploads

Some uploads are processed asynchronously and the API returns immediately with a request_id. This happens when:

• You enable “Upload Asynchronously” in the node, or
• The upload exceeds the server’s synchronous wait window, in which case the API switches to async mode automatically.

Leaving “Upload Asynchronously” enabled is recommended. Turning it off holds the HTTP connection open for the whole upload, which makes a proxy or execution timeout — and therefore a retry — more likely.

You have two ways to handle this in n8n:

1) Best-effort polling inside the node

• In Upload operations (Photos/Video/Text), enable “Wait for Completion”.
• Configure “Poll Interval (Seconds)” (default 10) and “Timeout (Seconds)”.
• The node sleeps between checks (using n8n’s sleep) and calls GET /api/uploadposts/status?request_id=... until success/failure or timeout.
• Note: This does not guarantee completion in hosted environments with strict execution limits.

2) Workflow-level polling (recommended for reliability)

• Use the Upload operation, read request_id from its output.
• Add a Wait node (e.g., 10s), then call “Get Upload Status” passing the request_id.
• Loop with an IF node until the status is final (success/failed) or a max attempts limit is reached.

Duplicate posts and retries

Every upload sends an Idempotency-Key. The API collapses two uploads carrying the same key within a 24-hour window into a single post, so a retried upload does not publish twice.

The key is derived from the workflow execution, the node and the item index, so it stays the same when n8n’s “Retry On Fail” re-runs the node, and changes when you genuinely start a new execution. Set the “Idempotency Key” field yourself only if you drive retries from outside n8n and need to control the key.

If you saw duplicate posts on an older version of this node, upgrade: versions before 0.1.51 sent no key at all, and a node-level retry after a network timeout would publish the post a second time.

Platform-Specific Options

#### Facebook

• Page Selection: Dynamic picker for Facebook pages (required for all operations).
• Media Type (Video): Reels or Stories.
• Video State: Published or Draft.
• Link (Text): URL for link preview in text posts.

#### LinkedIn

• Page Selection: Dynamic picker for organization pages (“Me” option for personal profiles).
• Visibility (Photos/Video): Public, Connections, Logged In, Container (video only).
• Video Description: User commentary for video posts.

#### Instagram

• Media Type: Image (feed photos), Stories, Reels (video).
• Video Options: Share to feed, collaborators (comma-separated usernames), cover URL, audio name, user tags (comma-separated), location ID, thumb offset.
• Photo Cover Index: Which photo to use as cover (0-based index).

#### TikTok

• Photo Options: Auto-add music, disable comments, photo cover index, brand content toggles (paid partnerships/third-party brands vs own business).
• Video Options: Privacy level (Public/Mutual Friends/Followers/Self), disable duet/stitch/comments, cover timestamp (ms), brand content toggles, AI-generated content flag, post mode (Direct Post/Media Upload).
• Brand Content: Separate toggles for paid partnerships and own business promotion.

#### TikTok Advanced Video Options

> Capability-gated. GET /api/uploadposts/users returns a capabilities
> array on each TikTok account (music, location, cover_image,
> covertimestamp, draft, photoprivacy, video_privacy,
> inboxfallback, profileanalytics). If the connection does not declare the capability an option
> needs, the API ignores that field, the post still publishes and the response
> includes a per-field warning — reconnect the TikTok account to enable it.
> These options are only sent when actually filled in, so leaving them at their
> defaults keeps the previous behaviour.

• Music (music): TikTok Music ID — the id of a track returned by GET /api/uploadposts/tiktok/music/trending or GET /api/uploadposts/tiktok/music/search (not its commercialmusicid) — plus music volume (0-100) and music start/end offsets in ms. The Music ID works on video and photo posts; the volume and the offsets are video-only, because TikTok’s photo contract takes the track id alone.

To pick a track by name inside a workflow, put an HTTP Request node before
this one calling
GET https://api.upload-post.com/api/uploadposts/tiktok/music/search?profile=&q=
with the header Authorization: Apikey , and feed tracks[0].id
into TikTok Music ID. It also accepts genre, countrycode, daterange
and limit. Note that TikTok has no music search endpoint: the search
runs over the trending charts Upload-Post caches per genre/country/period, so
it finds trending tracks, not TikTok’s entire catalogue.

• Original Sound Volume: Volume (0-100) of the video’s own audio when music is added. Keep it above 0 so the original audio is not muted. Music volume and original sound volume are only sent when a Music ID is set.
• Location (location): TikTok Location ID plus TikTok Location Name — TikTok requires both together. Works on video and photo posts.
• Cover Image URL (cover_image): Custom cover image, takes priority over the cover timestamp. Video only.
• Is AI Generated: AI-generated content disclosure. Works on video and photo posts.
• Upload to Draft (draft): Sends the video to TikTok drafts instead of publishing; TikTok then ignores the rest of the post settings. Video only.

> Privacy level on TikTok. privacy_level is accepted on video and photo
> uploads alike (capabilities videoprivacy / photoprivacy), but **TikTok
> decides per account which values are available**: a private account is offered
> Followers / Mutual Friends / Self Only and has no Public. Asking for one the
> account does not have fails with tiktokprivacyunavailable, and the error
> lists the ones it does have. The Account Default option on the TikTok
> Privacy Level (Video) field sends nothing and lets TikTok apply the account’s
> own setting — the only choice guaranteed to work on every account, and the
> default for new nodes. Photo posts default to Public. To pick a value up front,
> query GET /api/uploadposts/tiktok/settings?profile= from an HTTP
> Request node and read privacyleveloptions.

#### YouTube

• Video Metadata: Tags (comma-separated), category ID, privacy status (public/unlisted/private), embeddable, license, public stats viewable.
• Compliance: Made for kids declaration, self-declared made for kids (COPPA), contains synthetic media (AI transparency), has paid product placement (FTC).
• Geo-Restrictions: Allowed/blocked countries (ISO 3166-1 alpha-2 codes, mutually exclusive).
• Language Settings: Default language (title/description), default audio language.
• Recording Date: ISO 8601 timestamp.
• Thumbnail: Custom thumbnail via URL or binary file.

#### X (Twitter)

• Common Options: Tagged user IDs (comma-separated), reply settings (everyone/following/mentioned/verified/subscribers), geo place ID, long text as single post.
• Video/Photo Options: Nullcast (promoted-only posts), place ID.
• Text Options: Poll options (2-4 options, 25 chars max each, 5-10080 min duration), poll reply settings, post URL, quote tweet ID, card URI, direct message deep link.
• Community Features: Community ID, share with followers.
• Super Followers: Exclusive content for super followers.
• Validation: Poll options mutually exclusive with card URI, quote tweet ID, and direct message deep link.

#### Threads

• Text Options: Long text as single post (otherwise creates thread if >500 chars).
• Video Options: Description override support.

#### Pinterest

• Board Selection: Dynamic picker for Pinterest boards (required).
• Link: Optional link attachment.
• Video Cover: URL, base64 data with content type, or keyframe timestamp.

#### Reddit

• Text Options: Subreddit (without r/), flair ID for post categorization.

Validation Rules & Restrictions

#### X (Twitter) Poll Validation

• Options Count: Must contain 2-4 non-empty options.
• Option Length: Each option cannot exceed 25 characters.
• Duration: Must be between 5 and 10080 minutes (5 minutes to 7 days).
• Mutually Exclusive: Poll options cannot be used with Card URI, Quote Tweet ID, or Direct Message Deep Link.

#### Platform-Specific Requirements

• Facebook: Page selection is required for all operations.
• Pinterest: Board selection is required for all operations.
• LinkedIn Photos: Only supports PUBLIC visibility (API limitation).
• YouTube: Allowed/blocked countries are mutually exclusive.
• Instagram Video: Media type automatically defaults to REELS if invalid, IMAGE for photos.
• TikTok Photos: Media type automatically defaults to IMAGE if invalid.

#### File Handling

• Photos: Comma-separated list supporting both file paths and URLs.
• Videos: Single file path or URL.
• YouTube Thumbnails: Supports both URL and binary file uploads.
• Pinterest Covers: Multiple options (URL, base64 data with content type, or keyframe timestamp).

#### Scheduling

• Date Format: Automatic conversion to ISO 8601 with UTC timezone if not provided.
• Asynchronous Processing: Automatic fallback to async mode if upload exceeds 59 seconds.

Title & Description Overrides

• Title / Main Content: Generic title used across platforms.
• Platform Title Overrides: [platform]title (e.g., xtitle, pinteresttitle, threadstitle).

– Available for: instagram, facebook, tiktok, linkedin, x, youtube, pinterest, threads

• Description (Optional): Generic description used for LinkedIn, Facebook, YouTube, Pinterest, TikTok when supported.
• Platform Description Overrides: [platform]description (e.g., youtubedescription, linkedin_description).

– Available for: facebook, tiktok, linkedin, youtube, pinterest

• First Comment: Generic first comment posted right after publishing.
• Platform First Comment Overrides: [platform]firstcomment (e.g., instagramfirstcomment, tiktokfirstcomment).

– Available for: instagram, facebook, x, threads, youtube (video only), reddit, bluesky, linkedin, tiktok (media only).
– TikTok needs the comments capability on the profile’s TikTok account.

⚠️ Runtime Validations: The node performs automatic validations at runtime including poll constraints, mutually exclusive field checks, and platform-specific requirements. Invalid configurations will throw descriptive error messages.

Related docs:

• Profiles & JWT reference (context): User Profiles API

Resources

• n8n community nodes documentation
• Upload Post Website
• Upload Post API Documentation

Compatibility

Tested with n8n version 1.x.
Requires Node.js version 20.15 or later.

Development

If you want to contribute to this node or run it locally for development:

1. Clone this repository: git clone https://github.com/Upload-Post/n8n-nodes-upload-post (replace your-github-username)
2. Install dependencies: npm i
3. Build the node: npm run build
4. Link the package to your n8n instance for testing. Refer to Run your node locally.

License

MIT