Skip to content

Instagram Reels catalog audio API

The Instagram Reels catalog audio API covers three linked steps: linking an eligible professional Instagram account via Facebook Login, looking up tracks in the Instagram audio library, and attaching catalog music to a single-video Reel. Below you will find the precise request shapes for each step, the checks that decide whether audio features are available, and the ways publishing can fail so your client can handle them deliberately.

Why Facebook Login is needed for catalog audio

Many publishing flows need nothing more than a straightforward Instagram link, and that simpler route remains available. A separate set of Instagram Graph API capabilities, though, sits behind Facebook Login. Searching the audio catalog and attaching music to a Reel fall into that second group. Those capabilities presuppose a professional account tied to a Facebook Page, suitable Meta permissions, and a Facebook user token that is still active. Choosing between the two login routes therefore depends on whether your workflow needs Facebook-dependent features. Once linked through Facebook Login, the same connection can also drive Instagram publishing, analytics, comments, messaging, and comment-to-DM automation, and the post-creation API stays the same.

Connect Instagram through Facebook

Begin by requesting a connection URL that sets loginMethod to facebook_login, as illustrated in the Connect Instagram through Facebook Login example. Direct the person to the URL returned. Following authorization, they see the professional Instagram accounts associated with Pages they administer and pick one; the resulting tokens are then stored securely. Eligibility rests on three points: the Instagram account is a Business or Creator account, a Facebook Page is linked to it, and the person performing the connection has management rights over both the Page and the Instagram account. When the Meta app belongs to the customer, first save that Facebook OAuth app and include its appId in the connection request.

Search the Instagram audio library

With an eligible account linked, query the catalog by track title, performer, or a phrase, following the Search the Instagram audio library for music example. Leaving q out returns trending material instead. Setting audioType to original_sound switches the search from licensed music to original audio. A returned item carries an audioId alongside its title, audio type, performer where provided, duration, and any preview links supplied by Meta. Keep the audioId, since publishing relies on that identifier. Preview and download links are short-lived, so persisting them is unreliable; instead, pass a saved audioId back to the search endpoint whenever fresh metadata is needed.

Publish a Reel with catalog music

To attach music, place an audioConfiguration object inside platformSpecificData for the Instagram target, as shown in the Publish a single-video Reel with catalog music example. Two volume controls shape the mix: audioVolume sets the catalog track level, while videoVolume sets the level of the video's own sound. Each accepts a whole number between 1 and 100, and each defaults to 100 when omitted. This music option applies exclusively to a single-video Reel; photos, carousels, and Stories are outside its scope. The worked example pairs audioId 482851939985510 with audioVolume 80 and videoVolume 45, meaning the catalog track sits at 80 and the original video sound at 45.

Audio availability can change

The catalog exposed through the API may not mirror what appears inside the Instagram app, and what a given account can use may differ depending on licensing terms and region. For that reason the chosen track is checked again at the moment the Reel is published. Should Meta have withdrawn the track, or should the account have lost access to it, publishing ends in an error rather than going out without the selected music. Treat availability as a publish-time question, not a search-time guarantee, and design retries around picking a fresh audioId when a track has gone.

Existing Instagram connections remain unchanged

Facebook Login is an addition, not a replacement. Accounts already linked through Direct Instagram Login continue to work, and that route remains sensible when Facebook-dependent features are unnecessary. Integration responses expose platformMetadata.loginMethod together with capability flags, so client code can branch on platformMetadata.capabilities.catalogAudio before rendering any audio picker. That check keeps the interface honest for direct-login accounts, for Facebook authorizations that have lapsed, and for accounts lacking publishing rights. When a Facebook authorization does lapse, reconnecting through Facebook Login restores it; if Meta returns the same Instagram account identity, the integration and its scheduled posts carry over.

Start building

A practical starting point is the Instagram Audio Library Search, which lets you look up tracks, listen to previews, and copy audio IDs directly in a browser. For connection parameters, capability checks, headless account selection, and publishing examples, consult the Instagram platform guide. Both destinations are linked below as proposed internal links.

Input contract: required, optional, and defaulted fields
FieldLocationRequired / optionalType / enum / default (as captured)Notes
loginMethodQuery parameter on GET /v1/connect/instagramRequired for Facebook Login pathEnum value: facebook_loginSelects Facebook Login instead of Direct Instagram Login.
appIdConnection request, for customer-owned Meta appOptional / conditionalIdentifier as captured (illustrative)Pass when using a saved Facebook OAuth app.
accountIdQuery parameter on GET /v1/instagram/audio; also Instagram target field on POST /v1/postsRequiredIdentifier as captured (illustrative)Identifies the connected Instagram account.
audioTypeQuery parameter on GET /v1/instagram/audioOptional in captured example; shown as musicEnum: music, original_soundmusic searches licensed catalog music; original_sound searches original audio.
qQuery parameter on GET /v1/instagram/audioOptionalSearch phrase as capturedSearch by title, artist, or phrase. Omit to browse trending results.
audioIdSearch result; also platformSpecificData.audioConfiguration.audioId on POST /v1/postsRequired for publishing with catalog audioIdentifier as captured (illustrative)Save from search results; store this, not expiring preview/download URLs.
audioVolumeplatformSpecificData.audioConfigurationOptionalWhole number 1 to 100; default 100Controls the catalog track volume.
videoVolumeplatformSpecificData.audioConfigurationOptionalWhole number 1 to 100; default 100Controls the video's original sound volume.
platformMetadata.loginMethodIntegration responseResponse fieldValue as capturedCheck to distinguish Facebook Login from Direct Instagram Login.
platformMetadata.capabilities.catalogAudioIntegration responseResponse fieldCapability flag as capturedCheck before showing an audio picker.

Captured source contract; illustrative_unexecuted. Types shown only where captured; other values are illustrative placeholders.

Direct Instagram Login versus Facebook Login
CriterionDirect Instagram LoginFacebook Login
Linked Facebook Page requiredNoYes
Account typeInstagram account connection (existing connections unchanged)Instagram Business or Creator account linked to a Facebook Page
Catalog-audio searchNot described as the Facebook-dependent path in the sourceSupported for eligible accounts
Reel catalog music publishingNot described as the Facebook-dependent path in the sourceSupported for eligible accounts, single-video Reel only
Existing connectionsKeep working; Facebook Login is optionalReconnect through Facebook Login if authorization expires; integration and scheduled posts preserved when Meta returns the same Instagram account identity

Captured source contract; illustrative_unexecuted

Failure matrix
Failure caseWhat happensCheck / recovery
Ineligible account (not Business/Creator, not linked to a Facebook Page, or user cannot manage Page/account)Account cannot use the Facebook Login catalog-audio pathVerify all three account conditions before connection.
Expired Facebook authorizationFacebook-dependent features stop working for that integrationReconnect through Facebook Login; integration and scheduled posts are preserved when Meta returns the same Instagram account identity.
Removed or unavailable track at publish timePost fails with a clear error; Reel is not published silently without the selected musicRevalidate at publish time; search again and save a current audioId.
Unsupported media type (photo, carousel, or Story)Catalog audio option is not supportedUse catalog audio only with a single-video Reel.
Missing catalogAudio capabilityAudio picker should not be shownCheck platformMetadata.capabilities.catalogAudio before showing the picker.

Captured source contract; illustrative_unexecuted

Frequently asked questions

When should I choose Facebook Login instead of Direct Instagram Login?

Use Facebook Login when catalog audio is needed. The account must be a Business or Creator account linked to a Facebook Page, with the connecting person able to manage both. Check platformMetadata.capabilities.catalogAudio before presenting audio options.

What should I save from an audio search result?

Store the audioId returned by search. Preview and download links may expire, while the identifier is what publishing uses. Passing audioId back to the search endpoint refreshes saved track metadata.

Which Reel formats support catalog music, and what happens if a track disappears?

Catalog audio is limited to a single-video Reel. Photos, carousels, and Stories do not support this option. At publish time the track is checked again; if it is no longer available to the account, publishing fails rather than posting without the chosen music.

Connect Instagram through Facebook Login
curl "{{API_BASE_URL}}/v1/connect/instagram?loginMethod=facebook_login" \
  -H "x-access-key: YOUR_API_KEY"
Search the Instagram audio library for music
curl "{{API_BASE_URL}}/v1/instagram/audio?accountId=ACCOUNT_ID&audioType=music&q=summer" \
  -H "x-access-key: YOUR_API_KEY"
Publish a single-video Reel with catalog music
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "ACCOUNT_ID",
        "platformSpecificData": {
          "audioConfiguration": {
            "audioId": "482851939985510",
            "audioVolume": 80,
            "videoVolume": 45
          }
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'