How to Automate Instagram Story Publishing using the API

Understanding the Instagram Stories API

Setting Up Instagram Graph API Authentication

Stories publishing uses the same OAuth 2.0 long-lived tokens as other Instagram Graph API operations. The instagram_business_content_publish scope is what enables programmatic publishing. Short-lived tokens (1 hour) must be immediately exchanged for 60-day long-lived tokens after the OAuth flow completes.

1. 1Create a Business App at developers.facebook.com
2. 2Add the Instagram product and configure Instagram Business Login
3. 3Request instagram_business_basic and instagram_business_content_publish in App Review > Permissions
4. 4Implement OAuth redirect: https://www.facebook.com/v25.0/dialog/oauth?client_id={app-id}&redirect_uri={uri}&scope=instagram_business_basic,instagram_business_content_publish
5. 5Exchange authorization code at https://graph.facebook.com/v25.0/oauth/access_token
6. 6Exchange short-lived token for 60-day token: GET https://graph.instagram.com/access_token?grant_type=fb_exchange_token&client_id={app-id}&client_secret={secret}&fb_exchange_token={token}
7. 7Get the user's Instagram Business account ID: GET https://graph.instagram.com/v25.0/me?fields=id,username&access_token={token}
8. 8Schedule automated refresh every 50 days: GET https://graph.instagram.com/refresh_access_token?grant_type=ig_refresh_token&access_token={token}

1import requests
2import os
3
4IG_USER_ID = os.environ['IG_USER_ID']
5ACCESS_TOKEN = os.environ['IG_ACCESS_TOKEN']
6
7def get_long_lived_token(app_id, app_secret, short_token):
8    resp = requests.get('https://graph.instagram.com/access_token', params={
9        'grant_type': 'fb_exchange_token',
10        'client_id': app_id,
11        'client_secret': app_secret,
12        'fb_exchange_token': short_token,
13    })
14    resp.raise_for_status()
15    return resp.json()['access_token']
16
17def test_stories_permission():
18    """Verify the token has content publish scope by checking account info."""
19    resp = requests.get(
20        f'https://graph.instagram.com/v25.0/{IG_USER_ID}',
21        params={'fields': 'id,username,account_type', 'access_token': ACCESS_TOKEN}
22    )
23    resp.raise_for_status()
24    data = resp.json()
25    print(f'Account: @{data["username"]} ({data["account_type"]})')
26    if data['account_type'] == 'PERSONAL':
27        raise ValueError('Personal accounts cannot use the Instagram Graph API. Switch to Business/Creator.')
28    return data

Key endpoints

1{"media_type": "STORIES", "image_url": "https://example.com/story.jpg", "access_token": "EAAB..."}

1{"id": "17889615691580904"}

1{"status_code": "FINISHED", "id": "17889615691580904"}

1{"creation_id": "17889615691580904", "access_token": "EAAB..."}

1{"id": "17895695668004550"}

1{"data": [{"quota_usage": 2, "config": {"quota_total": 100, "quota_duration": 86400}}]}

Step-by-step automation

1# Verify the story image URL is accessible
2curl -I "https://example.com/story-image.jpg"
3# Check Content-Type should be image/jpeg

1# Image Story
2curl -X POST \
3  "https://graph.instagram.com/v25.0/${IG_USER_ID}/media" \
4  -d "media_type=STORIES" \
5  -d "image_url=https://example.com/story.jpg" \
6  -d "access_token=${ACCESS_TOKEN}"
7
8# Video Story
9curl -X POST \
10  "https://graph.instagram.com/v25.0/${IG_USER_ID}/media" \
11  -d "media_type=STORIES" \
12  -d "video_url=https://example.com/story.mp4" \
13  -d "access_token=${ACCESS_TOKEN}"

1# Poll status
2curl -s "https://graph.instagram.com/v25.0/${CONTAINER_ID}?fields=status_code&access_token=${ACCESS_TOKEN}"
3
4# Publish when FINISHED
5curl -X POST \
6  "https://graph.instagram.com/v25.0/${IG_USER_ID}/media_publish" \
7  -d "creation_id=${CONTAINER_ID}" \
8  -d "access_token=${ACCESS_TOKEN}"

Complete working code

Complete Story publishing scheduler: validates media specs, checks publishing quota, creates the Story container, polls until ready, publishes, and schedules a metrics collection job 23 hours later before Story expiry.

1#!/usr/bin/env python3
2"""Instagram Story Publisher - cron job or queue worker."""
3import os
4import time
5import logging
6import requests
7
8logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')
9log = logging.getLogger(__name__)
10
11IG_USER_ID = os.environ['IG_USER_ID']
12ACCESS_TOKEN = os.environ['IG_ACCESS_TOKEN']
13BASE = 'https://graph.instagram.com/v25.0'
14
15def ig_get(path, params):
16    params['access_token'] = ACCESS_TOKEN
17    r = requests.get(f'{BASE}{path}', params=params, timeout=30)
18    r.raise_for_status()
19    return r.json()
20
21def ig_post(path, data):
22    data['access_token'] = ACCESS_TOKEN
23    r = requests.post(f'{BASE}{path}', data=data, timeout=30)
24    r.raise_for_status()
25    return r.json()
26
27def check_quota():
28    d = ig_get(f'/{IG_USER_ID}/content_publishing_limit', {'fields': 'config,quota_usage'})
29    item = d['data'][0]
30    log.info(f'Quota: {item["quota_usage"]}/{item["config"]["quota_total"]}')
31    return item['quota_usage'] < item['config']['quota_total']
32
33def create_story(image_url=None, video_url=None):
34    body = {'media_type': 'STORIES'}
35    if image_url:
36        body['image_url'] = image_url
37    elif video_url:
38        body['video_url'] = video_url
39    else:
40        raise ValueError('Must provide image_url or video_url')
41    return ig_post(f'/{IG_USER_ID}/media', body)['id']
42
43def wait_ready(container_id, timeout=300):
44    deadline = time.time() + timeout
45    delay = 5
46    while time.time() < deadline:
47        status = ig_get(f'/{container_id}', {'fields': 'status_code'})['status_code']
48        log.info(f'Container {container_id}: {status}')
49        if status == 'FINISHED':
50            return
51        if status in ('ERROR', 'EXPIRED'):
52            raise ValueError(f'Container failed: {status}')
53        delay = min(delay * 2, 30)
54        time.sleep(delay)
55    raise TimeoutError('Container did not finish in time')
56
57def publish_story(container_id):
58    return ig_post(f'/{IG_USER_ID}/media_publish', {'creation_id': container_id})['id']
59
60def get_story_insights(media_id):
61    """Fetch Story insights. Call within 23 hours of publishing."""
62    try:
63        data = ig_get(f'/{media_id}/insights', {'metric': 'impressions,reach,exits', 'period': 'lifetime'})
64        return {item['name']: item['values'][0]['value'] for item in data['data']}
65    except Exception as e:
66        log.warning(f'Could not fetch insights for {media_id}: {e}')
67        return {}
68
69def publish_story_flow(image_url=None, video_url=None):
70    if not check_quota():
71        log.warning('Quota exhausted')
72        return None
73    container_id = create_story(image_url=image_url, video_url=video_url)
74    log.info(f'Container created: {container_id}')
75    wait_ready(container_id, timeout=120 if video_url else 60)
76    media_id = publish_story(container_id)
77    log.info(f'Story live! Media ID: {media_id} (expires in 24h)')
78    return media_id
79
80if __name__ == '__main__':
81    media_id = publish_story_flow(image_url='https://your-cdn.com/story.jpg')
82    if media_id:
83        print(f'Published: {media_id}')

Error handling

Rate Limits for Instagram Stories API

1import time
2import requests
3
4def with_retry(fn, max_retries=4):
5    """Execute fn with exponential backoff on rate limit errors."""
6    for attempt in range(max_retries):
7        try:
8            return fn()
9        except requests.HTTPError as e:
10            if e.response.status_code in (400, 429):
11                code = e.response.json().get('error', {}).get('code')
12                if code in (17, 4, 32, 613):  # Rate limit codes
13                    wait = min(60 * (2 ** attempt), 3600)
14                    print(f'Rate limited. Waiting {wait}s')
15                    time.sleep(wait)
16                    continue
17            raise
18    raise Exception('Max retries exceeded')

• Check the 100 posts/day cap before creating Story containers — not after a failed publish attempt
• Monitor X-Business-Use-Case-Usage header on every response; pause when call_count percentage hits 80%
• For bulk Story campaigns (posting multiple Stories in quick succession), add 5-second delays between publish calls
• Schedule Story analytics collection jobs 23 hours after publish to capture insights before the 24-hour expiry
• Use the content_publishing_limit endpoint at the start of your publishing run to plan how many Stories you can post

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Design Stories for the 9:16 aspect ratio (1080x1920px) — landscape or square images will be cropped by Instagram
• Keep key content in the center 75% of the Story frame — Instagram UI overlays cover the top and bottom ~12.5% each
• Do not try to add interactive stickers (polls, questions, links, countdowns) via API — they are not supported and will be silently dropped
• For video Stories, stay well under 8MB — compress videos aggressively since mobile Story viewers don't benefit from high bitrates
• Never use captions for Stories via the API — Story captions are not supported and will be ignored without an error
• Schedule Story analytics collection 23 hours post-publish — wait until near-expiry to capture the most complete engagement data
• Create containers at publish time (within minutes of the target time) — never pre-create Story containers hours or days ahead

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations