# Instagram publishing and insights

> Publish and schedule photos, videos, carousels, Reels and Stories, and read account and post insights.

This page applies to Instagram accounts that are already [connected](/en/connect/instagram/). Publishing requires the `instagram_content_publish` permission; insights require `instagram_manage_insights`. Without them, the route answers `403` [`instagram_scope_missing`](/en/errors#instagram_scope_missing) until you reconnect the account.

## Publish

Meta does not schedule posts: Messajo stores the request and publishes at the set time. In the panel, use **Publications → New publication**; through the API, `POST /v1/publications`.

![New publication screen with account, type, media, caption counters and the choice between publishing now and scheduling](../../../../assets/screenshots/publication-composer-en-US.png)

### Types

| `type` | Media | Note |
|---|---|---|
| `photo` | 1 image | Feed post |
| `video` | 1 video | Becomes Reels with `share_to_feed` always on (Meta discontinued plain feed videos) |
| `reel` | 1 video | Accepts a cover (`cover`), `thumb_offset_ms`, `share_to_feed` and `audio_name` |
| `carousel` | 2 to 20 items, images and/or videos | One container per item and one for the carousel |
| `story` | 1 image or video | No visible caption |

Each item comes as a `media_id` (file uploaded with `POST /v1/media` and `purpose=publication`) or as a public `url`. They also accept `alt_text`, `user_tags`, `collaborators` (up to 3) and `location_id`.

### Limits

| Rule | Value |
|---|---|
| Caption | up to 2,200 characters, 30 hashtags and 20 mentions (`@`) |
| Image | **JPEG**, up to 8 MiB. PNG and WebP sent by `media_id` are converted to JPEG before publishing |
| Video | MP4 or MOV, up to 300 MiB (Stories up to 100 MiB) |
| Scheduling | from now up to 75 days ahead |
| Meta quota | 100 publications per account in a rolling 24 h (`GET /v1/connections/{id}/publishing-limit`) |

Outside these rules, the answer is `422` [`validation_failed`](/en/errors#validation_failed) with the field in `details`.

### Public URL

Meta **downloads** the media from the URL: it must be reachable from the internet. A `media_id` becomes a signed S3 storage link valid for 24 h.A private-network URL is rejected with `422` [`media_url_not_public`](/en/errors#media_url_not_public).

### Scheduling and status

An empty `scheduled_at` (or one within the next minute) publishes now; in the future, the publication is **Scheduled** and a task runs at the right time, with a sweep every minute as a safety net. While it is `scheduled` or `queued`, you can edit it (`PATCH /v1/publications/{id}`) or cancel it (`POST /v1/publications/{id}/cancel`); after that, [`publication_not_editable`](/en/errors#publication_not_editable).

| `status` | What happens |
|---|---|
| `scheduled` | Waiting for the set time |
| `queued` | Queued to publish. With Meta's quota full, it tries again every hour; 24 h past the time, it fails with [`publishing_limit_reached`](/en/errors#publishing_limit_reached) |
| `creating` | Creating the media containers on Meta |
| `processing` | Meta is processing the media. More than 30 min fails with [`container_timeout`](/en/errors#container_timeout) |
| `publishing` | Asking for the publication |
| `published` | Published, with `external_media_id` and `permalink` |
| `failed` | Failed; the reason is in `error` (Messajo code + Meta code and status) |
| `canceled` | Canceled by you |

The `publication.published` and `publication.failed` events go out ([catalog](/en/webhooks/events/#catalog)).

### Never repeated blindly

If Meta does not answer the publish request (timeout, `5xx`), there is no way to know whether the post went out. Messajo does **not** publish again: it checks the container status on Meta. If it was already published, it marks `published` and looks for the post; if the container is ready and not published, it tries once more; if it is still processing, it waits. If it was published but the post was not found, it stays `published` without `external_media_id`, and that publication does not accept `retry`. A regular `failed` publication can be retried with `POST /v1/publications/{id}/retry`, which creates new containers.

## Insights

In the panel, **Insights** shows the chosen account over 7, 28 or 90 days: reach, views, accounts engaged, interactions, followers gained and lost, the daily series and this month's audience. Below, the posts with each one's metrics.

![Insights screen with reach and engagement cards, the daily chart and the posts table](../../../../assets/screenshots/insights-en-US.png)

| `/v1` route | What it returns |
|---|---|
| `GET /connections/{id}/insights` | Account metrics: `reach`, `views`, `accounts_engaged`, `total_interactions`, `likes`, `comments`, `shares`, `saves`, `replies`, `reposts`, `follows_and_unfollows`, `profile_links_taps` (per day) and `follower_demographics`, `engaged_audience_demographics` |
| `GET /connections/{id}/posts` · `/posts/{post_id}` | The account's posts, with likes and comments |
| `GET /connections/{id}/posts/{post_id}/insights` | Post metrics, by type (feed, Reels or story) |

- **Delay:** Meta can take up to 48 h to update the numbers. Messajo caches each query for 15 min.
- `impressions` was discontinued by Meta and is rejected with `validation_failed`.
- A carousel item has no insights of its own: `422` [`insights_not_available`](/en/errors#insights_not_available). Neither does a story with an audience below 5 people.
- **Stories:** a story's metrics disappear 24 h after it expires, and the story insights webhook is still to be confirmed on the unified login. So Messajo takes a snapshot of the active stories every hour; the insight of an expired story comes from that snapshot, with `source: "snapshot"` and the time in `captured_at` (in the panel, "captured at …").
