Skip to content

Search Instagram Reel Audio API

The Search Instagram Reel Audio API lets a developer search for or revalidate Instagram Reel audio for a specific account. You call GET /v1/instagram/audio with a required accountId, optionally narrow the lookup with audioId, audioType, or q, and receive an audio array describing each matching track. This page documents the exact method, path, header, query parameters, response fields, and error shapes so an implementation can match the contract without guessing field names or types.

Search or revalidate Instagram Reel audio

Use this operation when a Reel workflow needs to find audio by search text, confirm a known audioId, or revalidate the details returned for an earlier lookup. The request is a GET to /v1/instagram/audio. Every call is scoped by accountId, so validate that value before sending the request: it must be a 24-character hexadecimal string matching ^[a-fA-F0-9]{24}$. If accountId is missing or does not match that pattern, expect the request to fail validation rather than return audio results.

Authorization uses the x-access-key header. Send your access key as the header value, shown in the worked request example as <token>. Keep the header name exactly as x-access-key, including its lowercase spelling, and do not substitute a different authorization scheme. A missing or invalid key is a failure check to handle separately from the documented 400, 404, and 502 response bodies, because the captured contract does not specify an additional status for authentication failures.

For a search, supply accountId and q. The q parameter is an optional string with a maximum length of 200 characters. For a direct lookup or revalidation, supply accountId and audioId, where audioId is an optional string matching ^\d+$ (digits only). You can also filter by audioType, an optional string that must be either music or original_sound. The captured contract does not specify what happens when q and audioId are supplied together, so do not rely on a combined behaviour; choose the parameter that matches your task and treat the other as unused until that behaviour is specified.

A successful 200 response returns a JSON object with a required audio array. Each item in that array has required fields audioId, title, and audioType, plus displayArtist, durationInMs, downloadUrl, and onPlatformAudioPreviewLink, each of which is required in the object but may be null. That distinction matters in code: check for null before using displayArtist as a display name, before treating durationInMs as a number, and before opening downloadUrl or onPlatformAudioPreviewLink as a link. The audioType value in a response item is a string; the captured response schema does not restrict it to the music and original_sound values that apply to the audioType query parameter.

Error responses for 400, 404, and 502 share the same captured JSON shape: a required error string and an optional code string. The failure matrix below maps each status to that shape without inventing specific codes or causes, because the source does not supply them. When you receive a 400, inspect error and code to identify the validation problem and correct the request. When you receive a 404, treat the lookup as not found for the supplied parameters. When you receive a 502, treat the call as failed upstream; the captured contract does not specify retry behaviour, so do not assume an automatic retry policy. In all three cases, parse the body defensively, since code is optional and may be absent.

Authorization

Send the access key in the x-access-key header on every request to GET /v1/instagram/audio. The header name is x-access-key and the value is your token. Verify the header is present before debugging query parameters, because an authentication problem will prevent the documented query and response contract from being exercised.

Query Parameters

All query parameters are passed in the URL query string. accountId is the only required parameter. audioId, audioType, and q are each optional. Validate each value against its captured constraint before the call: accountId against ^[a-fA-F0-9]{24}$, audioId against ^\d+$, audioType against the music and original_sound enum, and q against the length <= 200 limit. The input contract table below is the authoritative field map for these parameters.

Response Body

The endpoint returns application/json for 200, 400, 404, and 502. On 200, the body contains the audio array described in the response field map. On 400, 404, and 502, the body contains the error and code shape described in the failure matrix. Parse the response by status first, then by the corresponding body shape, and do not assume a successful audio array is present on an error status.

200 application/json

Each entry in the 200 audio array describes one Instagram Reel audio item. Use audioId as the identifier for later lookups or revalidation, title as the track or sound title, and audioType to distinguish the kind of audio returned. Use displayArtist for the artist name when it is not null, durationInMs for the duration in milliseconds when it is not null, downloadUrl when a download link is available, and onPlatformAudioPreviewLink when a preview link on the platform is available. Because the last four fields can be null, guard every use with a null check.

400 application/json

A 400 response uses the shared error shape with a required error string and an optional code string. Treat this status as a request problem to correct, such as a parameter that fails its captured pattern, enum, or length constraint, and read error and code from the body for the specific message returned.

404 application/json

A 404 response uses the same error shape. Treat this status as a lookup that did not find a matching result for the supplied parameters, and read error and code from the body rather than assuming a cause that the captured contract does not state.

502 application/json

A 502 response uses the same error shape. Treat this status as a failed call and read error and code from the body. The captured contract does not specify retry behaviour or a cause for this status, so handle it as an error response and do not invent a retry rule.

Worked example

The worked request example shows the exact GET method, the unchanged /v1/instagram/audio path with a modular origin, the accountId query parameter, and the x-access-key header. The worked 200 response example shows the audio array and every response field name exactly as captured. The error response example shows the shared error and code shape used for 400, 404, and 502. Replace the placeholder accountId and token values with real values for your account before calling, and validate the response fields against the field maps in the tables.

Query parameter input contract
ParameterRequiredTypeConstraint
accountIdRequiredstringMatches ^[a-fA-F0-9]{24}$
audioIdOptionalstringMatches ^\d+$
audioTypeOptionalstringEnum: music, original_sound
qOptionalstringLength <= 200

Exact captured query contract for GET /v1/instagram/audio.

200 response field map
FieldRequired in objectTypeNotes
audioRequiredarray<object>Top-level array of audio items
audio[].audioIdRequiredstringAudio identifier
audio[].titleRequiredstringAudio title
audio[].audioTypeRequiredstringAudio type string
audio[].displayArtistRequiredstring | nullMay be null
audio[].durationInMsRequirednumber | nullMay be null
audio[].downloadUrlRequiredstring | nullMay be null
audio[].onPlatformAudioPreviewLinkRequiredstring | nullMay be null

Exact captured 200 response field map; nullable fields may be null.

Failure matrix for 400, 404 and 502
StatusContent typeBody fieldsHandling
400application/jsonerror (required string), code (optional string)Correct the request using error and code
404application/jsonerror (required string), code (optional string)Treat the lookup as not found for the supplied parameters
502application/jsonerror (required string), code (optional string)Treat the call as failed; no retry behaviour specified

Only the captured error/code shape is documented; specific codes and causes are not supplied.

Worked GET request for Instagram Reel audio
curl -X GET "{{API_BASE_URL}}/v1/instagram/audio?accountId=string" -H "x-access-key: <token>"
Example 200 response body
{
  "audio": [
    {
      "audioId": "string",
      "title": "string",
      "audioType": "string",
      "displayArtist": "string",
      "durationInMs": 0,
      "downloadUrl": "string",
      "onPlatformAudioPreviewLink": "string"
    }
  ]
}
Example error response body for 400, 404 and 502
{
  "error": "string",
  "code": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
accountId#1accountIdstring__0Yeskind: schemaMatch; value: ^[a-fA-F0-9]{24}$
audioId#2audioIdstring__0Nokind: schemaMatch; value: ^\d+$
audioType#3audioTypestring__0No
audioType#3audioType[variant1]string__0_extends:__1kind: schemaValueIn; value: "music"
audioType#3audioType[variant2]string__0_extends:__2kind: schemaValueIn; value: "original_sound"
q#4qstring__0Nokind: schemaLength; value: length <= 200
response#5responseobject__0
response#5response.audioarray<object>__1Yes
response#5response.audio[]object__2
response#5response.audio[].audioIdstring__3Yes
response#5response.audio[].titlestring__4Yes
response#5response.audio[].audioTypestring__5Yes
response#5response.audio[].displayArtiststring | null__6Yes
response#5response.audio[].displayArtist[variant1]string__6_extends:__7
response#5response.audio[].displayArtist[variant2]null__6_extends:__8
response#5response.audio[].durationInMsnumber | null__9Yes
response#5response.audio[].durationInMs[variant1]number__9_extends:__10
response#5response.audio[].durationInMs[variant2]null__9_extends:__11
response#5response.audio[].downloadUrlstring | null__12Yes
response#5response.audio[].downloadUrl[variant1]string__12_extends:__13
response#5response.audio[].downloadUrl[variant2]null__12_extends:__14
response#5response.audio[].onPlatformAudioPreviewLinkstring | null__15Yes
response#5response.audio[].onPlatformAudioPreviewLink[variant1]string__15_extends:__16
response#5response.audio[].onPlatformAudioPreviewLink[variant2]null__15_extends:__17
response#6responseobject__0
response#6response.errorstring__1Yes
response#6response.codestring__2No