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, so 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, so 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

Optional fields

Add these to the container create call (step 1).

Field	Applies to	What it does
`alt_text`	Single images and carousel image children	Alt text for screen readers, up to 1000 characters
`user_tags`	Images, videos, stories, carousel children	Tag public accounts: `[{"username":"someuser","x":0.5,"y":0.8}]`. `x`/`y` position the tag on images
`collaborators`	Images, reels, carousel parent	Invite accounts to collaborate: `["username1","username2"]`. Once they accept, the post also shows on their profile
`location_id`	Feed posts and reels	Tag a place by its Facebook Page id. The Page must have location data
`thumb_offset`	Videos and reels	Cover frame, in milliseconds from the start. Ignored when `cover_url` is set
`audio_name`	Reels	Name the reel’s audio. You can only set it once

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": "Team day",
  "alt_text": "Four people at a wooden table with laptops",
  "user_tags": [{ "username": "someuser", "x": 0.5, "y": 0.8 }]
}'

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, so 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"

# Optional fields: --alt-text, --tag username[:x,y] (repeatable), --location <page-id>, --thumb-offset <ms>, --audio-name <name>

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

Optional fields

Trial reels

Publishing quota

Publish with the CLI

Publish with MCP

Next steps

​How publishing works

​Media requirements

​Optional fields

​Trial reels

​Publishing quota

​Publish with the CLI

​Publish with MCP

​Next steps

How publishing works

Media requirements

Optional fields

Trial reels

Publishing quota

Publish with the CLI

Publish with MCP

Next steps