How to build a social media scheduler on an API: the queue, media and post statuses
To build a social media scheduler on easyCoexistence's Partner API, your backend sends each post to POST /channels/:id/posts with its text, media and a publish_at from 1 minute to 90 days ahead. easyCoexistence copies the media at once and publishes the post at its time on Instagram, Facebook, TikTok or LinkedIn, reporting each step as a status and through post.published and post.failed events.
How far ahead the posts API schedules on Instagram, Facebook, TikTok and LinkedIn; the earliest time is 1 minute away.
Largest image and largest video easyCoexistence copies when a post is scheduled; a bigger file is refused at that moment.
When a post a network rate-limited is tried again, before it is marked failed.
API-published posts an Instagram account can make in a moving 24 hours; a carousel counts as one.
TikTok's cap on video posts per account through its publishing endpoint, with at most six in a minute.
What does a scheduler need from the API?
Five things: a place to upload files, a call that queues a post for one account, a queue that publishes on time, a way to change its mind, and word of what happened. The posts API gives each of them on the same ec_live_ key that connects your customers, so the calendar, the approval flow and the composer stay in your product.
How do you schedule a post?
With one POST per account to https://easycoexistence.com/api/v1/channels/:id/posts, where :id is the channel_id from the customer's connect session. publish_at is ISO 8601 with a Z or an offset; leave it out to publish now. The answer is 201 with the post, or 422 when a post meant for now failed. An Idempotency-Key header is honored, so a request repeated after a timeout does not queue the post twice. The body takes:
- text: the caption, message or commentary; media: a list of {url, type} or {
media_id}. - link: a Facebook link post or a LinkedIn article, with a title on LinkedIn.
ig_type: IMAGE, CAROUSEL, REELS or STORIES, inferred from the media when left out.- title and
disable_commentfor TikTok photo posts;image_altfor a LinkedIn image.
curl -X POST https://easycoexistence.com/api/v1/channels/$CHANNEL_ID/posts \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Idempotency-Key: campaign-311-ig" \
-H "Content-Type: application/json" \
-d '{
"text": "Three looks for the weekend",
"media": [
{ "url": "https://cdn.example.com/looks/1.jpg", "type": "image" },
{ "url": "https://cdn.example.com/looks/2.jpg", "type": "image" }
],
"ig_type": "CAROUSEL",
"publish_at": "2026-11-20T09:00:00-05:00"
}'How does the scheduler handle media?
Either by link or by upload. A public HTTPS link goes straight into media; a file your users upload goes to POST /media, as the request body with its Content-Type and Content-Length, or as {"url"}, and the media_id it returns goes into the post. When a post is scheduled, easyCoexistence copies its files, so your link only has to work at that moment. A web page instead of a file, a 404, the wrong type or a file over 30 MB for images or 1 GB for videos is refused then, not on the morning of the post.
What can each network's post carry?
The queue checks each post against the network's rules before accepting it, and a post that breaks one is refused with a message naming the rule, so your composer can show the problem while the user is still editing. Each network takes:
Which statuses does a post move through?
Six, which GET /posts/:id and GET /posts report, alongside publish_at, the post's link once it is live and the network's error when it failed:
- scheduled: in the queue, waiting for its time.
- publishing: handed to the network.
- processing: the network is still working on it, as with a TikTok video or an Instagram container.
- published: live, with its link.
- failed: refused or not confirmed;
may_be_publishedmarks one the network may have received. - canceled: removed before it went out, by you or because its channel was removed or suspended.
How do you edit, cancel or retry a post?
PATCH /posts/:id changes a scheduled post's time or text, and a TikTok photo post's title; to change its media, cancel it and schedule a new one. DELETE /posts/:id cancels it. POST /posts/:id/retry publishes a failed post again, now. A post a network rate-limited is retried on its own after 5 minutes, 30 minutes and 2 hours, and a post marked may_be_published needs a look at the account before any retry.
How does your scheduler hear what happened?
From events and from the list. The status events URL set under Profile, Developers receives post.published and post.failed, signed with X-EC-Signature like every other event, with the post and its channel, so your calendar can mark each one live or flag it. GET /posts takes status, from, to and limit for calendar views, and GET /channels/:id/posts lists one account. A post that fails in the background also emails your account's owner, at most once per channel every 3 hours.
How do LinkedIn posts fit a scheduler?
With a person approving each one. LinkedIn's API Terms restrict using its APIs to automate posting, so a scheduler keeps every LinkedIn post as a draft in your product until a named person approves it, then sends it with its publish_at. Recurring rules, feeds and bulk imports should target the other networks, and leave LinkedIn to posts someone has reviewed.
Common mistakes
- Sending publish_at without an offset. A local time with no Z or offset is refused, so send 2026-11-20T09:00:00-05:00 rather than the bare clock time your user picked.
- Retrying a post marked may_be_published straight away. The network may already show it, so check the account first, or the post goes out twice.
- Repeating a timed-out POST without an Idempotency-Key. Give each post its own key, so a repeated request returns the post already queued instead of scheduling a second copy.
- Linking PNG files for Instagram. Instagram's publishing API takes JPEG only, and the post is refused when it is scheduled, so convert images in your upload step.
easyCoexistence gives your scheduler one queue for your customers' Instagram, Facebook, TikTok and LinkedIn accounts, and more channels, through each network's official API: media copied when a post is scheduled, six statuses, retries for rate limits and signed post events, with every connection monitored 24/7. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Can one request schedule a post on several networks?
Each request targets one channel, so send one per account, each with its own Idempotency-Key, and adapt the text to each network's limits.
Does the posts API schedule YouTube videos?
YouTube schedules natively. Upload the video through YouTube's API as private with publishAt, using the token from GET /channels/:id?credentials=1, and YouTube makes it public at that time.
Can my users see their scheduled posts in easyCoexistence's dashboard?
The Posts screen belongs to your account, so your team sees Needs attention, Coming up and Published there, with Cancel, Retry and Dismiss. Your users see the calendar your product builds from GET /posts.
How much does easyCoexistence cost for a social media scheduler?
US$ 9 to US$ 0.75 per connected account per month, falling as your users connect more, with scheduling included and the first 3 days free.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on