Posts

Publish trial reels on Instagram via API

A trial reel is shown first to people who do not follow the account yet. With format reels and instagram.trial_graduation_strategy, Connect publishes the reel in that mode, with no app review and no token handling.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "reel-trial-12",
  "format": "reels",
  "caption": "Teste novo: o que acha?",
  "media": [
    {
      "type": "video",
      "url": "https://cdn.example.com/trial.mp4"
    }
  ],
  "instagram": {
    "trial_graduation_strategy": "SS_PERFORMANCE"
  }
}

What you can do

  • Publish a reel as a trial reel with a single option, trial_graduation_strategy.
  • Pick MANUAL so the account decides whether to promote the reel to the profile.
  • Pick SS_PERFORMANCE so Instagram promotes it on its own if it performs well.
  • Combine it with cover, audio, collaborators and first comment, as on any reel.

Rules and limits

  • trial_graduation_strategy only works with format reels and accepts MANUAL or SS_PERFORMANCE.
  • Reels takes exactly 1 video.
  • The answer is 202: publishing runs in the background. Follow it with GET /posts/{uuid}.
  • external_reference is required and Idempotency-Key lets you retry without duplicating.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account.
formatstringYesPost format. On Instagram: feed, reels or story. On Facebook: feed, reels or story.
captionstringNoCaption. On Instagram, up to 2200 characters, 30 hashtags and 20 mentions. Stories carry no caption.
mediaarrayYesList of media, in order. Each item has type and url.
media.urlstringYesPublic https:// URL the network can download (up to 2048 characters).
instagram.trial_graduation_strategystringNoPublishes as a trial reel. MANUAL: the account decides whether to promote it to the profile. SS_PERFORMANCE: Instagram promotes it if it performs well. Reels only.
instagram.share_to_feedbooleanNoWhether the reel also shows on the profile grid. Reels only.

Who it is for

  • Content testing

    Your SaaS publishes variations of a video as trial reels to measure reach among non-followers before going to the profile.

  • Agency

    Validate creatives for several clients: SS_PERFORMANCE promotes only the ones that perform well.

  • Growth AI agent

    An agent publishes a batch of test reels and, with MANUAL, leaves the final call to the account.

Works with

  • Instagram Business
  • Instagram

Frequently asked questions

What is a trial reel?

A reel shown first to non-followers. You set how it gets promoted to the profile: MANUAL or SS_PERFORMANCE.

What is the difference between MANUAL and SS_PERFORMANCE?

With MANUAL the account decides whether to promote the reel to the profile. With SS_PERFORMANCE Instagram promotes it automatically if it performs well.

Can I use trial_graduation_strategy on feed or story?

No. The option only works on reels.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.