> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Instagram audio metadata

> Look up the details of a single Instagram audio track by its id

export const InstagramAudioNotice = () => <Warning>
  <strong>Requires Instagram linked through Facebook Login.</strong> Instagram's Audio API is only available to accounts connected via <strong>Facebook Login</strong>, which needs a Facebook Page connected to the Instagram account. Accounts connected with <strong>Instagram Login</strong> (the Ayrshare default) cannot search, look up, or attach audio, and every audio request returns <code>code: 514</code>.
  <br /><br />
  This is a Meta restriction, not an Ayrshare one. Meta's documentation states the Audio API "is only available on the Instagram API with Facebook Login. It is not supported on the Instagram API with Instagram Login." No permission or plan upgrade changes it.
  <br /><br />
  <strong>Three things are required:</strong>
  <br />
  1. An Instagram <strong>Business</strong> or <strong>Creator</strong> account<br />
  2. A <strong>Facebook Page connected</strong> to that Instagram account<br />
  3. Instagram linked to Ayrshare with <strong>Instagram Login disabled</strong>, so the Facebook Login flow is used
  <br /><br />
  See the <a href="/docs/dashboard/connect-social-accounts/instagram#music-attach-eligibility-facebook-login-required">step-by-step setup guide</a>.
</Warning>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

Retrieve the details of one audio track by its `audioId`. Use this to confirm a stored id is still valid, or to show a track's title and artwork before publishing.

<InstagramAudioNotice />

## Header Parameters

<HeaderAPI />

## Path Parameters

<ParamField path="audioId" type="string" required>
  The track id, as returned by [audio search](/docs/apis/media/search-instagram-audio). An id Instagram
  does not recognize returns `code: 517`.
</ParamField>

## Response Fields

The track's fields are returned flat on the response object rather than nested. Instagram does not return every field for every track, so treat all fields except `audioId` as optional.

<ResponseField name="status" type="string">`success` when the track was found.</ResponseField>
<ResponseField name="audioId" type="string">The track id, echoed back.</ResponseField>
<ResponseField name="title" type="string">Track title.</ResponseField>
<ResponseField name="displayArtist" type="string">Artist name as Instagram displays it.</ResponseField>
<ResponseField name="durationMs" type="integer">Track length in milliseconds.</ResponseField>
<ResponseField name="thumbnailUrl" type="string">Cover artwork thumbnail URL.</ResponseField>
<ResponseField name="audioType" type="string">Either `music` or `original_sound`.</ResponseField>

<ResponseField name="isAdsEligible" type="boolean">
  Whether the track may be used in an ad.
</ResponseField>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "audioId": "17901234567890123",
    "title": "Summer Nights",
    "displayArtist": "The Example Band",
    "durationMs": 32000,
    "thumbnailUrl": "https://scontent.example.com/cover.jpg",
    "audioType": "music",
    "isAdsEligible": true
  }
  ```

  ```json 400: Track unavailable theme={"system"}
  {
    "status": "error",
    "code": 517,
    "action": "post",
    "message": "The selected audio track is unavailable. It may be an invalid audio id, restricted in your region, or not licensed for this use. Please choose a different track using the Instagram audio search endpoint and try again.",
    "platform": "instagram"
  }
  ```
</ResponseExample>

<Note>
  **Availability is region-dependent.** Meta returns the same error for an id that does not exist,
  one that is not licensed in the account's region, and one that is not licensed for this use. All
  three report `517`, so a track that resolves for one account can legitimately fail for another.
  Look up an id rather than assuming a stored one still works.
</Note>

## Errors

| Code | Meaning                                                                                      |
| ---- | -------------------------------------------------------------------------------------------- |
| 156  | Instagram is not linked to this profile.                                                     |
| 161  | Instagram's authorization expired or was revoked. Relink the account.                        |
| 239  | Instagram rejected the request for an account-level reason.                                  |
| 258  | Instagram returned a malformed response or an unmapped failure.                              |
| 425  | The connection is missing a required Instagram permission. Relink and grant all permissions. |
| 435  | Instagram's rate limit was reached. Wait before retrying.                                    |
| 514  | Instagram is linked with Instagram Login. The Audio API requires Facebook Login.             |
| 516  | The `audioId` is missing or empty.                                                           |
| 517  | Instagram does not recognize the id, or the track is unavailable to this account.            |

Codes 514 to 518 are described in [Instagram Reels audio errors](/docs/errors/errors-ayrshare#instagram-reels-audio-errors); the rest are in the [Ayrshare error reference](/docs/errors/errors-ayrshare).

## Next Steps

<Card title="Search for a track" icon="magnifying-glass" href="/docs/apis/media/search-instagram-audio" horizontal />

<Card title="Attach the track to a Reel" icon="music" href="/docs/apis/post/social-networks/instagram#adding-music-to-a-reel" horizontal />