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.
| Parameter | Required | Type | Constraint |
|---|---|---|---|
| accountId | Required | string | Matches ^[a-fA-F0-9]{24}$ |
| audioId | Optional | string | Matches ^\d+$ |
| audioType | Optional | string | Enum: music, original_sound |
| q | Optional | string | Length <= 200 |
Exact captured query contract for GET /v1/instagram/audio.
| Field | Required in object | Type | Notes |
|---|---|---|---|
| audio | Required | array<object> | Top-level array of audio items |
| audio[].audioId | Required | string | Audio identifier |
| audio[].title | Required | string | Audio title |
| audio[].audioType | Required | string | Audio type string |
| audio[].displayArtist | Required | string | null | May be null |
| audio[].durationInMs | Required | number | null | May be null |
| audio[].downloadUrl | Required | string | null | May be null |
| audio[].onPlatformAudioPreviewLink | Required | string | null | May be null |
Exact captured 200 response field map; nullable fields may be null.
| Status | Content type | Body fields | Handling |
|---|---|---|---|
| 400 | application/json | error (required string), code (optional string) | Correct the request using error and code |
| 404 | application/json | error (required string), code (optional string) | Treat the lookup as not found for the supplied parameters |
| 502 | application/json | error (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.
curl -X GET "{{API_BASE_URL}}/v1/instagram/audio?accountId=string" -H "x-access-key: <token>"{
"audio": [
{
"audioId": "string",
"title": "string",
"audioType": "string",
"displayArtist": "string",
"durationInMs": 0,
"downloadUrl": "string",
"onPlatformAudioPreviewLink": "string"
}
]
}{
"error": "string",
"code": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | Yes | kind: schemaMatch; value: ^[a-fA-F0-9]{24}$ | |
| audioId#2 | audioId | string | __0 | No | kind: schemaMatch; value: ^\d+$ | |
| audioType#3 | audioType | string | __0 | No | ||
| audioType#3 | audioType[variant1] | string | __0_extends:__1 | kind: schemaValueIn; value: "music" | ||
| audioType#3 | audioType[variant2] | string | __0_extends:__2 | kind: schemaValueIn; value: "original_sound" | ||
| q#4 | q | string | __0 | No | kind: schemaLength; value: length <= 200 | |
| response#5 | response | object | __0 | |||
| response#5 | response.audio | array<object> | __1 | Yes | ||
| response#5 | response.audio[] | object | __2 | |||
| response#5 | response.audio[].audioId | string | __3 | Yes | ||
| response#5 | response.audio[].title | string | __4 | Yes | ||
| response#5 | response.audio[].audioType | string | __5 | Yes | ||
| response#5 | response.audio[].displayArtist | string | null | __6 | Yes | ||
| response#5 | response.audio[].displayArtist[variant1] | string | __6_extends:__7 | |||
| response#5 | response.audio[].displayArtist[variant2] | null | __6_extends:__8 | |||
| response#5 | response.audio[].durationInMs | number | null | __9 | Yes | ||
| response#5 | response.audio[].durationInMs[variant1] | number | __9_extends:__10 | |||
| response#5 | response.audio[].durationInMs[variant2] | null | __9_extends:__11 | |||
| response#5 | response.audio[].downloadUrl | string | null | __12 | Yes | ||
| response#5 | response.audio[].downloadUrl[variant1] | string | __12_extends:__13 | |||
| response#5 | response.audio[].downloadUrl[variant2] | null | __12_extends:__14 | |||
| response#5 | response.audio[].onPlatformAudioPreviewLink | string | null | __15 | Yes | ||
| response#5 | response.audio[].onPlatformAudioPreviewLink[variant1] | string | __15_extends:__16 | |||
| response#5 | response.audio[].onPlatformAudioPreviewLink[variant2] | null | __15_extends:__17 | |||
| response#6 | response | object | __0 | |||
| response#6 | response.error | string | __1 | Yes | ||
| response#6 | response.code | string | __2 | No |