Skip to content

Instagram Reels Search API (V1) ​

GET
API health status
Healthy Available Limited Mostly unavailable No data
Loading health status...

Searches Instagram Reels by keyword or hashtag with token-based pagination. Use it to discover short-form videos, monitor topics, and continue through matching results.

Parameters ​

NameInTypeRequiredDefaultDescription
tokenquerystringYes-Access token for the API service.
keywordquerystringYes-The search keyword or hashtag to filter Reels.
paginationTokenquerystringNoToken used for retrieving the next page of results.

Code Samples ​

bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE'
text
I want to use the "Reels Search (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE
API Endpoint: BASE_URL + /api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/instagram/reels-search-v1-en.json

Parameters:
- token (query): Access token for the API service. (Required)
- keyword (query): The search keyword or hashtag to filter Reels. (Required)
- paginationToken (query): Token used for retrieving the next page of results.

Return format: safely handle JSON or text according to the actual Content-Type.

Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set the request timeout to 120 seconds. If 120 seconds is too long for your use case, use at least 60 seconds, but a small number of requests may time out before receiving a result.
3. Business Code Reference:
   - 0: Success
   - 100: Invalid or Inactive Token
   - 301: Collection Failed. Please Retry.
   - 302: Rate Limit Exceeded
   - 303: Daily Quota Exceeded
   - 400: Invalid Parameters
   - 500: Internal Server Error
   - 600: Permission Denied
   - 601: Insufficient Balance
   - 602: Token Budget Exceeded
4. Code 601 means the shared account balance is insufficient. Code 602 means the current API token's own cumulative budget limit has been reached. Token budget limits do not transfer funds out of the shared account balance.

Please help me write a script in my preferred programming language to call this API and handle the response.
python
import requests

BASE_URL = "https://api.justoneapi.com"  # Provided by OpenAPI servers

url = BASE_URL + "/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE"
response = requests.get(url, timeout=120)
print(response.status_code)
if response.content:
    content_type = response.headers.get("content-type", "").lower()
    if "json" in content_type:
        try:
            print(response.json())
        except ValueError:
            print(response.text)
    elif content_type.startswith("text/") or "xml" in content_type or content_type.split(";", 1)[0].strip() in {"application/javascript", "application/x-www-form-urlencoded", "application/graphql"}:
        print(response.text)
    else:
        with open("response.bin", "wb") as output:
            output.write(response.content)
        print(f"Saved {len(response.content)} bytes to response.bin")
js
const BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
const url = BASE_URL + "/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE";

const response = await fetch(url, {
  method: "GET",
  signal: AbortSignal.timeout(120000)
});
console.log(response.status);
const responseBytes = await response.arrayBuffer();
if (responseBytes.byteLength) {
  const contentType = (response.headers.get("content-type") || "").toLowerCase();
  const mediaType = contentType.split(";", 1)[0].trim();
  const textual = contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || ["application/javascript", "application/x-www-form-urlencoded", "application/graphql"].includes(mediaType);
  if (textual) {
    const responseText = new TextDecoder().decode(responseBytes);
    let data = responseText;
    if (contentType.includes("json")) {
      try { data = JSON.parse(responseText); } catch { /* Keep the raw body. */ }
    }
    console.log(data);
  } else {
    console.log(`Received ${responseBytes.byteLength} binary bytes`);
  }
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class Main {
    public static void main(String[] args) throws Exception {
        final String BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
        final String url = BASE_URL + "/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE";

        HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(120)).build();
        HttpRequest.Builder builder = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .timeout(Duration.ofSeconds(120))
            .method("GET", HttpRequest.BodyPublishers.noBody());

        HttpRequest request = builder.build();

        HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
        System.out.println(response.statusCode());
        String contentType = response.headers().firstValue("content-type").orElse("").toLowerCase();
        String mediaType = contentType.split(";", 2)[0].trim();
        if (contentType.startsWith("text/") || contentType.contains("json") || contentType.contains("xml") || mediaType.equals("application/javascript") || mediaType.equals("application/x-www-form-urlencoded") || mediaType.equals("application/graphql")) {
            System.out.println(new String(response.body(), StandardCharsets.UTF_8));
        } else {
            Files.write(Path.of("response.bin"), response.body());
            System.out.println("Saved " + response.body().length + " bytes to response.bin");
        }
    }
}
go
package main

import (
	"fmt"
	"io"
	"os"
	"strings"
	"net/http"
	"time"
)

const BASE_URL = "https://api.justoneapi.com" // Provided by OpenAPI servers

func main() {
	client := &http.Client{Timeout: 120 * time.Second}
	url := BASE_URL + "/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE"
	req, _ := http.NewRequest("GET", url, nil)
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	fmt.Println(resp.StatusCode)
	bodyBytes, _ := io.ReadAll(resp.Body)
	contentType := strings.ToLower(resp.Header.Get("Content-Type"))
	mediaType := strings.TrimSpace(strings.SplitN(contentType, ";", 2)[0])
	if strings.HasPrefix(contentType, "text/") || strings.Contains(contentType, "json") || strings.Contains(contentType, "xml") || mediaType == "application/javascript" || mediaType == "application/x-www-form-urlencoded" || mediaType == "application/graphql" {
		fmt.Println(string(bodyBytes))
	} else {
		os.WriteFile("response.bin", bodyBytes, 0600)
		fmt.Printf("Saved %d bytes to response.bin\n", len(bodyBytes))
	}
}
php
<?php
$BASE_URL = 'https://api.justoneapi.com'; // Provided by OpenAPI servers
$url = $BASE_URL . '/api/instagram/search-reels/v1?token=YOUR_API_KEY&keyword=VALUE';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$contentType = strtolower((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE));
curl_close($ch);
echo $status . PHP_EOL;
$mediaType = trim(explode(';', $contentType, 2)[0]);
if (str_starts_with($contentType, 'text/') || str_contains($contentType, 'json') || str_contains($contentType, 'xml') || in_array($mediaType, ['application/javascript', 'application/x-www-form-urlencoded', 'application/graphql'], true)) {
    echo $response;
} else {
    file_put_contents('response.bin', $response);
    echo 'Saved ' . strlen($response) . ' bytes to response.bin' . PHP_EOL;
}

Response Fields ​

Key fields in a successful response (code = 0).

Results and pagination5 fields

data

One Reels search page and its reported continuation token.

FieldTypeDescription
dataobjectPage contents for the current Reels query.
data.countintegerNumber of Reel entries reported on this page.
data.itemsarrayReels returned on this page. The list may be empty.
data.items[]objectOne Reel in the search results.
pagination_tokenstringPass the returned continuation token as paginationToken with the same keyword to request another page. An empty page can include a token.
Reel metadata13 fields

data.data.items[]

FieldTypeDescription
idstringReel identifier as returned by Instagram.
codestringShort code used in the Reel link.
permalinkstringDirect Instagram URL for the Reel when present.
media_typeintegerNumeric media type code. Searches in the verified samples returned code 2 for video.
product_typestringProduct type label. The verified Reel samples returned clips.
media_formatstringMedia format label returned for the Reel.
is_videobooleanWhether the media is a video.
taken_atintegerPublication time as a Unix timestamp in seconds.
taken_at_tsintegerPublication timestamp field returned in Unix seconds.
taken_at_datestringFormatted publication timestamp returned with the Reel.
is_paid_partnershipbooleanWhether the Reel is marked as a paid partnership.
is_pinnedbooleanWhether the Reel is marked as pinned.
is_in_profile_gridbooleanWhether the Reel is shown in the author's profile grid.
Video and imagery46 fields

data.data.items[]

FieldTypeDescription
video_urlstringDirect video URL returned for the Reel.
thumbnail_urlstringPreview image URL returned for the Reel.
video_durationnumberNumeric duration reported for the video in the response's original unit.
video_codecstringVideo codec label returned with the Reel.
has_audiobooleanWhether the Reel has audio.
original_widthintegerOriginal media width in pixels.
original_heightintegerOriginal media height in pixels.
number_of_qualitiesintegerReported number of video quality variants.
video_versionsarrayAvailable video versions listed in the response.
video_versions[]objectOne video version of the Reel.
video_versions[].idstringIdentifier of this video version.
video_versions[].typeintegerPlatform code for this video version type.
video_versions[].urlstringURL of this video version.
video_versions[].widthintegerWidth of this video version in pixels.
video_versions[].heightintegerHeight of this video version in pixels.
video_versions[].bandwidthintegerBandwidth value reported for this encoded version.
image_versionsobjectImage candidates and preview assets for the Reel.
image_versions.itemsarrayCandidate image versions listed for the Reel.
image_versions.items[]objectOne image candidate.
image_versions.items[].urlstringURL of this image version.
image_versions.items[].widthintegerWidth of this image version in pixels.
image_versions.items[].heightintegerHeight of this image version in pixels.
image_versions.items[].is_spatial_imagebooleanWhether Instagram marks the image as spatial.
image_versions.additional_itemsobjectAdditional first-frame images returned with the Reel.
image_versions.additional_items.first_frameobjectFirst-frame image version.
image_versions.additional_items.first_frame.urlstringURL of this image version.
image_versions.additional_items.first_frame.widthintegerWidth of this image version in pixels.
image_versions.additional_items.first_frame.heightintegerHeight of this image version in pixels.
image_versions.additional_items.first_frame.is_spatial_imagebooleanWhether Instagram marks the image as spatial.
image_versions.additional_items.igtv_first_frameobjectAdditional first-frame image in the IGTV field.
image_versions.additional_items.igtv_first_frame.urlstringURL of this image version.
image_versions.additional_items.igtv_first_frame.widthintegerWidth of this image version in pixels.
image_versions.additional_items.igtv_first_frame.heightintegerHeight of this image version in pixels.
image_versions.additional_items.igtv_first_frame.is_spatial_imagebooleanWhether Instagram marks the image as spatial.
image_versions.scrubber_spritesheet_info_candidatesobjectSprite sheets for timeline previews.
image_versions.scrubber_spritesheet_info_candidates.defaultobjectDefault timeline preview sprite sheet configuration.
image_versions.scrubber_spritesheet_info_candidates.default.sprite_urlsarraySprite sheet image URLs.
image_versions.scrubber_spritesheet_info_candidates.default.sprite_urls[]stringURL of one sprite sheet image.
image_versions.scrubber_spritesheet_info_candidates.default.sprite_widthintegerSprite sheet width in pixels.
image_versions.scrubber_spritesheet_info_candidates.default.sprite_heightintegerSprite sheet height in pixels.
image_versions.scrubber_spritesheet_info_candidates.default.thumbnail_widthintegerWidth of each timeline preview thumbnail in pixels.
image_versions.scrubber_spritesheet_info_candidates.default.thumbnail_heightintegerHeight of each timeline preview thumbnail in pixels.
image_versions.scrubber_spritesheet_info_candidates.default.thumbnails_per_rowintegerNumber of thumbnails per row in the sheet.
image_versions.scrubber_spritesheet_info_candidates.default.total_thumbnail_num_per_spriteintegerTotal number of thumbnails reported per sheet.
image_versions.scrubber_spritesheet_info_candidates.default.max_thumbnails_per_spriteintegerMaximum number of thumbnails reported per sheet.
image_versions.scrubber_spritesheet_info_candidates.default.file_size_kbintegerReported sprite sheet file size in kilobytes.
Creator and collaborators18 fields

data.data.items[]

FieldTypeDescription
userobjectAuthor account returned for the Reel.
user.idstringInstagram account identifier as text.
user.usernamestringInstagram username shown for this account.
user.full_namestringDisplay name reported for the account.
user.profile_pic_urlstringProfile picture URL for the account.
user.profile_pic_idstringIdentifier of the account's profile picture.
user.is_privatebooleanWhether the profile is marked private.
user.is_verifiedbooleanWhether the account displays a verified status.
user.follower_countintegerFollower count reported for the account.
coauthor_producersarrayCoauthor accounts associated with the Reel, when present.
coauthor_producers[]objectOne coauthor account.
coauthor_producers[].idstringInstagram account identifier as text.
coauthor_producers[].usernamestringInstagram username shown for this account.
coauthor_producers[].full_namestringDisplay name reported for the account.
coauthor_producers[].profile_pic_urlstringProfile picture URL for the account.
coauthor_producers[].profile_pic_idstringIdentifier of the account's profile picture.
coauthor_producers[].is_privatebooleanWhether the profile is marked private.
coauthor_producers[].is_verifiedbooleanWhether the account displays a verified status.
Caption and subtitles25 fields

data.data.items[]

FieldTypeDescription
captionobjectCaption attached to the Reel.
caption.idstringCaption record identifier as text.
caption.textstringCaption text as posted by the author.
caption.text_translationstring | nullTranslated caption text when included in the response.
caption.created_atintegerTime recorded for caption creation as a Unix timestamp in seconds.
caption.hashtagsarrayHashtags listed with the caption. The list may be empty.
caption.hashtags[]stringOne hashtag string reported for the caption.
caption.mentionsarrayMentions listed with the caption. The list may be empty.
caption.mentions[]stringOne mention string reported for the caption.
caption.user_idstringAccount identifier recorded on the caption.
caption.userobjectAccount attached to the caption.
caption.user.idstringInstagram account identifier as text.
caption.user.usernamestringInstagram username shown for this account.
caption.user.full_namestringDisplay name reported for the account.
caption.user.profile_pic_urlstringProfile picture URL for the account.
caption.user.profile_pic_idstringIdentifier of the account's profile picture.
caption.user.is_privatebooleanWhether the profile is marked private.
caption.user.is_verifiedbooleanWhether the account displays a verified status.
video_subtitles_enabledbooleanWhether video subtitles are enabled for the Reel.
video_subtitles_localestring | nullLocale value reported for the Reel's subtitles when available.
video_subtitles_uristring | nullSubtitle file URI when available.
translated_video_subtitlesarray | nullTranslated subtitle versions when included in the response.
translated_video_subtitles[]objectOne translated subtitle version.
translated_video_subtitles[].languagestringLanguage label of the translated subtitles.
translated_video_subtitles[].uristringURI for this translated subtitle version.
Engagement metrics14 fields

data.data.items[]

FieldTypeDescription
play_countintegerPlay count reported for the Reel.
ig_play_countintegerInstagram play count reported separately for the Reel.
fb_play_countinteger | nullFacebook play count when included in the response.
like_countinteger | nullLike count reported for the Reel, which may be null.
ig_like_countintegerInstagram like count when included in the response.
fb_like_countinteger | nullFacebook like count when included in the response.
comment_countintegerComment count reported for the Reel.
share_countinteger | nullShare count reported for the Reel.
repost_countinteger | nullRepost count reported for the Reel, which may be null.
share_count_disabledbooleanWhether sharing counts are marked disabled for the Reel.
like_and_view_counts_disabledbooleanWhether like and view counts are marked disabled for the Reel.
can_resharebooleanWhether the Reel is marked as resharable.
can_savebooleanWhether the Reel is marked as saveable.
has_more_commentsboolean | nullWhether the individual Reel is marked as having more comments.
Audio information35 fields

data.data.items[]

FieldTypeDescription
clips_metadataobjectAudio metadata associated with the Reel.
clips_metadata.audio_typestringAudio category label returned for the Reel.
clips_metadata.audio_canonical_idstringCanonical audio identifier reported for the Reel.
clips_metadata.original_sound_infoobject | nullOriginal audio information when available.
clips_metadata.original_sound_info.audio_idstringOriginal audio identifier as text.
clips_metadata.original_sound_info.original_audio_titlestringTitle displayed for the original audio.
clips_metadata.original_sound_info.original_media_idstringIdentifier of the media associated with the original audio.
clips_metadata.original_sound_info.duration_in_msintegerDuration of the original audio in milliseconds.
clips_metadata.original_sound_info.progressive_download_urlstringOriginal audio playback URL when returned.
clips_metadata.original_sound_info.is_explicitbooleanWhether the original audio is marked explicit.
clips_metadata.original_sound_info.ig_artistobjectInstagram artist associated with the original audio.
clips_metadata.original_sound_info.ig_artist.idstringInstagram account identifier as text.
clips_metadata.original_sound_info.ig_artist.usernamestringInstagram username shown for this account.
clips_metadata.original_sound_info.ig_artist.full_namestringDisplay name reported for the account.
clips_metadata.original_sound_info.ig_artist.profile_pic_urlstringProfile picture URL for the account.
clips_metadata.original_sound_info.ig_artist.profile_pic_idstringIdentifier of the account's profile picture.
clips_metadata.original_sound_info.ig_artist.is_privatebooleanWhether the profile is marked private.
clips_metadata.original_sound_info.ig_artist.is_verifiedbooleanWhether the account displays a verified status.
clips_metadata.music_infoobject | nullMusic information when returned for the Reel.
clips_metadata.music_info.music_asset_infoobjectMetadata of the music asset used in the Reel.
clips_metadata.music_info.music_asset_info.idstringMusic asset identifier as text.
clips_metadata.music_info.music_asset_info.audio_idstringAudio identifier for the music asset.
clips_metadata.music_info.music_asset_info.titlestringTitle shown for the music asset.
clips_metadata.music_info.music_asset_info.display_artiststringArtist credit displayed for the music asset.
clips_metadata.music_info.music_asset_info.artist_idstring | nullArtist identifier returned for the music asset.
clips_metadata.music_info.music_asset_info.ig_usernamestring | nullInstagram username associated with this music asset when available.
clips_metadata.music_info.music_asset_info.duration_in_msintegerMusic asset duration in milliseconds.
clips_metadata.music_info.music_asset_info.cover_artwork_uristringCover artwork address for the music asset.
clips_metadata.music_info.music_asset_info.cover_artwork_thumbnail_uristringCover art thumbnail address for the music asset.
clips_metadata.music_info.music_asset_info.progressive_download_urlstringPlayback URL returned for the music asset.
clips_metadata.music_info.music_asset_info.fast_start_progressive_download_urlstringFast-start playback URL returned for the music asset.
clips_metadata.music_info.music_asset_info.has_lyricsbooleanWhether lyrics are marked available for the music asset.
clips_metadata.music_info.music_asset_info.is_explicitbooleanWhether the music asset is marked explicit.
clips_metadata.music_info.music_asset_info.highlight_start_times_in_msarrayHighlight start positions in milliseconds.
clips_metadata.music_info.music_asset_info.highlight_start_times_in_ms[]integerStart position of one highlight in milliseconds.
Place and content labels8 fields

data.data.items[]

FieldTypeDescription
locationobject | nullPlace tagged on the Reel when returned.
location.idstringIdentifier assigned to the tagged place.
location.namestringName of the tagged place.
location.short_namestringShort name of the tagged place.
location.citystringCity label returned for the tagged place.
ai_label_infoobject | nullAI disclosure label information when returned for the Reel.
ai_label_info.attribution_label_textstring | nullAttribution text displayed for the AI disclosure label.
ai_label_info.subtitle_textstringSupplemental text accompanying the AI disclosure label.

Response Example ​

Loading the response example...