Publish content

How publishing works

Publishing is a three-step flow:

Create a media container with your media URL and caption.
Poll the container until its status_code is FINISHED.
Images usually finish immediately. Videos take longer — poll about once per minute.
Publish the container.

There is no publish webhook. Polling is the only way to know a container is ready.
Containers expire after 24 hours. Meta has no scheduled publishing — publish when you want the post live.

# 1. Create a media container
curl -X POST "https://gateway.hookmyapp.com/meta/v25.0/${INSTAGRAM_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://example.com/photo.jpg",
  "caption": "New drop"
}'
# → { "id": "17900000000000001" }

# 2. Poll until FINISHED
curl "https://gateway.hookmyapp.com/meta/v25.0/17900000000000001?fields=status_code" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"
# → { "status_code": "FINISHED", "id": "17900000000000001" }

# 3. Publish
curl -X POST "https://gateway.hookmyapp.com/meta/v25.0/${INSTAGRAM_ACCOUNT_ID}/media_publish" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "creation_id": "17900000000000001" }'
# → { "id": "17850000000000000" }

Supply media as a public HTTPS URL. Meta downloads it from that URL — private links, localhost, and signed URLs that expire before the fetch all fail.
Some hosts block Meta’s fetcher; that surfaces as a misleading Only photo or video can be accepted as media type error. If you hit it, move the file to a host that serves it to any client.
Videos should be H.264 + AAC in an MP4 container — other codecs pass the URL check but fail processing with container status ERROR.

Media requirements

Type	Container fields	Limits
Image	`image_url`	JPEG only. Max 8 MB. Aspect ratio between 4:5 and 1.91:1
Reel	`media_type=REELS`, `video_url`, optional `cover_url`	Max 15 minutes, max 1 GB
Story	`media_type=STORIES`, `image_url` or `video_url`	Video max 60 seconds. No stickers or links. Expires after 24 hours
Carousel	`media_type=CAROUSEL`, `children` (containers created with `is_carousel_item=true`)	Max 10 items. Reels cannot be carousel items

Trial reels

A trial reel goes out to people who don’t follow you, so you can test a hook before it reaches your followers.
Add trial_params to a reel container — it only works with media_type=REELS.

curl -X POST "https://gateway.hookmyapp.com/meta/v25.0/${INSTAGRAM_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "media_type": "REELS",
  "video_url": "https://example.com/reel.mp4",
  "trial_params": { "graduation_strategy": "SS_PERFORMANCE" }
}'

`graduation_strategy`	What happens
`MANUAL`	You graduate the reel to your followers yourself, from the Instagram app
`SS_PERFORMANCE`	Instagram graduates it for you if it performs well

Poll and publish the container exactly as you would for a normal reel.
Meta gives you no way to read back whether an existing reel is a trial reel — track that on your side if you need it. With MCP, ask for a trial reel and say who graduates it — the publish_instagram_media tool takes trialParams.graduationStrategy as manual or automatic.

Publish https://example.com/reel.mp4 as a trial reel on Instagram channel ch_xxxxxxxx, graduated automatically if it performs.

Publishing quota

Meta allows 50 publishes per rolling 24 hours, currently being raised to 100.
Check your live quota and usage:

curl "https://gateway.hookmyapp.com/meta/v25.0/${INSTAGRAM_ACCOUNT_ID}/content_publishing_limit" \
  -H "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"

Container creation has its own limit: 400 containers per 24 hours.

Publish with the CLI

The CLI runs the whole container → poll → publish flow and prints the permalink.

# Publish image
hookmyapp instagram publish --channel @your-handle --image https://example.com/photo.jpg --caption "New drop"

# Publish reel
hookmyapp instagram publish --channel @your-handle --video https://example.com/reel.mp4 --reel --cover https://example.com/cover.jpg

# Publish story
hookmyapp instagram publish --channel @your-handle --image https://example.com/story.jpg --story

# Publish carousel (prefix video items with video: — plain URLs are images)
hookmyapp instagram publish --channel @your-handle --carousel https://example.com/1.jpg,video:https://example.com/2.mp4 --caption "Gallery"

Publish with MCP

Ask your agent to publish. The publish_instagram_media tool handles the full flow and returns the media ID and permalink.

Use HookMyApp MCP to publish https://example.com/photo.jpg to Instagram channel ch_xxxxxxxx with the caption "New drop".

See MCP for setup.

Next steps

Insights: Read reach and views for what you publish.
Comments: Reply to and moderate comments on your posts.

Getting started

Sending & receiving

Publish & engage

Tools

API Reference

How publishing works

Media requirements

Trial reels

Publishing quota

Publish with the CLI

Publish with MCP

Next steps

​How publishing works

​Media requirements

​Trial reels

​Publishing quota

​Publish with the CLI

​Publish with MCP

​Next steps

How publishing works

Media requirements

Trial reels

Publishing quota

Publish with the CLI

Publish with MCP

Next steps