URL: /code/integrations/instagram · Id: `page:/code/integrations/instagram`

# Instagram

> Your agents post your images, carousels and reels on schedule, answer comments and direct messages as you, and read what each post reached.

Your agents post your images, carousels and reels on schedule, answer comments and direct messages as you, and read what each post reached.

```text title="Run it · Ask"
Post my three rent-reminder slides as a carousel, and show me how it will look.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Post.publish({ handle: 'instagram:leaseline', format: 'carousel', media: ['files/slide-1', 'files/slide-2', 'files/slide-3'], body: 'The 3 texts that end late rent, one per slide. Save it for the 1st.' })
```

```json title="Run it · Response"
{
  "$type": "Post",
  "mode": "try",
  "stored": false,
  "venue": "instagram",
  "status": "published",
  "format": "carousel",
  "items": 3,
  "ratio": "4:5, from the first slide",
  "checks": {
    "images": "JPEG, 1080 × 1350, under 8 megabytes",
    "caption": "67 of 2,200 characters"
  },
  "postsLeftToday": 49
}
```

- **Connect:** Sign in once, 4 grants
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Find 25 creators who talk to property managers, about 0.95¢
- **Sites:** [Instagram](/venues#instagram)

## Connect once
1. Switch the account to a professional account in Instagram’s settings, if it is not one already.
2. Call `Integration.connect` with `system: 'social'` and `venue: 'instagram'`, then open the `connectUrl` it returns and sign in as that Instagram account.
3. Call `Handle.connect` to bind the account as your account.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Publish | Images, carousels and reels posted as you | `instagram_business_basic instagram_business_content_publish` |
| Comments | Replies to comments, and hiding or deleting the ones that break your rules | `instagram_business_manage_comments` |
| Direct messages | Answers to the messages people send you | `instagram_business_manage_messages` |
| Insights | Each post’s reach, saves and shares | `instagram_business_manage_insights` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops every call through Instagram at once and keeps the token; `Integration.resume` picks up from the same cursor. |
| Reconnect | `Integration.reconnect` returns a fresh `connectUrl` that lasts one hour, and keeps the Integration's id and cursor, so nothing imports twice. |
| Disconnect | `Integration.revoke` revokes the token with Instagram; every record it brought in stays in your records. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Post these three slides as a carousel with this caption. | [`Post.publish`](/code/apps/social/publish) | Your account | Free |
| Post the reel on Thursday at noon. | [`Post.schedule`](/code/apps/social/schedule) | Your account | Free |
| Answer each comment and direct message as me. | [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | Your account | Free |
| Which posts reached the most people this month, and which were saved? | [`Metric.query`](/code/apps/analytics-and-experiments/query) | Your account | Free |

Calls on your own account are free.

Reading this site’s public data needs no account: [`Prospect.find`](/code/data/people/find) is a Data call (the [three ways a call runs](/code/integrations#three-ways)).

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Post](https://startupbuilder.dev/business/nouns/post) | `media` | Your agent publishes | Your records |
| [Message](https://startupbuilder.dev/business/nouns/message) | `comment or message` | Someone comments or writes to you | The account |
| [Conversation](https://startupbuilder.dev/business/nouns/conversation) | `conversation` | A direct message thread opens | The account |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Post.published`, `Post.scheduled`, `Message.created` |
| Hears `comments` | Becomes `Message.created` |
| Hears `messages` | Becomes `Message.created` |
| Hears `mentions` | Becomes `Message.created` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| Posts through the API | 50 in a moving 24 hours, and a carousel counts as one; the agent reads what is left before each post | [`Post.publish`](/code/apps/social/publish) |
| A staged post | Instagram drops a staged post after 24 hours, so the agent stages it in the hour it publishes | [`Post.schedule`](/code/apps/social/schedule) |
| Account type | A professional account; a personal account refuses with `account-not-connected` until it switches | Every call |

## Field map
| Our field | Instagram’s field | Notes | Calls |
| --- | --- | --- | --- |
| `Post.body` | `caption` | 2,200 characters, 30 hashtags, 20 mentions | [`Post.publish`](/code/apps/social/publish), [`Post.schedule`](/code/apps/social/schedule) |
| `Post.format` | `media_type` | IMAGE, CAROUSEL, REELS or STORIES | [`Post.publish`](/code/apps/social/publish), [`Post.schedule`](/code/apps/social/schedule) |
| `Post.media` | `image_url or video_url` | A carousel holds up to 20 items, cropped to the first one’s ratio | [`Post.publish`](/code/apps/social/publish), [`Post.schedule`](/code/apps/social/schedule) |
| `Post.publishAt` | `media_publish` | Instagram has no scheduled publish; the platform holds the Post and publishes it then | [`Post.schedule`](/code/apps/social/schedule) |

## What try does here
Checks each image and video against Instagram’s specs and returns the post as it will show; no container is staged and nothing publishes.

## How long a connection lasts
A connection lasts 60 days per token, and the platform refreshes it once it is a day old, so a connection your agents use never runs out.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Formats
| Site | Format | Size | Limits |
| --- | --- | --- | --- |
| [Instagram](/venues#instagram) | Feed image | 320 to 1,440 pixels wide, 4:5 to 1.91:1 | JPEG only, up to 8 megabytes; caption 2,200 characters, 30 hashtags, 20 mentions |
| [Instagram](/venues#instagram) | Carousel | None. | Up to 20 images or videos, cropped to the first item’s ratio; counts as one post |
| [Instagram](/venues#instagram) | Reel | 9:16 | MOV or MP4, 3 seconds to 15 minutes, up to 300 megabytes, 23 to 60 frames a second |
| [Instagram](/venues#instagram) | Story | 9:16 | Image up to 8 megabytes; video 3 to 60 seconds, up to 100 megabytes |

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Organic social](/plays/organic-social), [Video ladder](/plays/video-ladder), [Creator partnership](/plays/creator-partnership), [Test with a creator](/plays/creator-probe), [Commission partners](/plays/commission-partners) |
| Strategies | [Launch and search](/strategy/launch-and-search), [Paid](/strategy/paid) |

## Used by
No Workflow, agent task or Service acts through it yet: your agents call it directly.

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Post.publish`](/code/apps/social/publish) | `POST /posts/publish` | Free |
| [`Post.schedule`](/code/apps/social/schedule) | `POST /posts/schedule` | Free |
| [`Conversation.answer`](https://startupbuilder.dev/business/nouns/conversation/answer) | `POST /conversations/answer` | Free |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | `POST /metrics/query` | Free |