# GET /v1/search/reels: Reel search API Finds reels for a text (q): caption, video, time and counts. Pass next_cursor back as cursor for the next page. - Call: `GET https://storiesfly.com/api/v1/search/reels` - Price **1 request** - Answers up to **30 minutes** old ## Parameters All parameters go in the query string. | Name | Type | Sent | Description | | --- | --- | --- | --- | | `q` | string | required | Text to search for, 1 to 100 characters. | | `cursor` | string | optional | The next_cursor of the page before. Leave it out for the first page. | ## Example request Put your own key in the header. ### cURL ```bash curl "https://storiesfly.com/api/v1/search/reels?q=coffee" \ -H "X-Api-Key: sf_live_your_key" ``` ### JavaScript ```javascript const res = await fetch( "https://storiesfly.com/api/v1/search/reels?q=coffee", { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } } ); const data = await res.json(); ``` ### Python ```python import os import requests r = requests.get( "https://storiesfly.com/api/v1/search/reels", params={"q": "coffee"}, headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]}, ) data = r.json() ``` ## Example response 200 OK · X-Units-Charged: 1 ```json { "posts": [ { "id": "4003633000379481394", "shortcode": "DePwwBupn0y", "url": "https://www.instagram.com/reel/DePwwBupn0y/", "owner": { "id": "327288580", "username": "adriaccopa" }, "taken_at": 1791490336, "taken_at_iso": "2026-10-08T20:12:16.000Z", "caption": "Spanish Latte ☕️🥛This delightful drink combines the sweetness of condensed milk and richness of double espresso flavor. Mix with ice cubes to taste for a rea…", "media_type": "reel", "pinned": false, "thumbnail_url": "https://instagram.fsjc1-4.fna.fbcdn.net/v/t51.71878-15/835596390_2207723176833877_3906341833166463548_n.jpg", "media": [ { "id": "4003633000379481394", "type": "video", "image_url": "https://instagram.fsjc1-4.fna.fbcdn.net/v/t51.71878-15/835596390_2207723176833877_3906341833166463548_n.jpg", "video_url": "https://instagram.fsjc1-4.fna.fbcdn.net/o1/v/t2/f2/m86/AQPJtIMMugvD0BfPVA1uy7jUONSdZmOu_AaZLrmo9urQDhDYTFqO-1iqfMSn-4f95rWKplUQYae-qZPyNdqoP-zn3Yexb7EHN9A8TqE.…", "width": 1080, "height": 1920, "video_duration": 16.252 } ], "likes": 94966, "comments": 241, "shares": 9374, "reposts": 1199, "views": 6423092, "saves": 12361, "video_duration": 16.252, "counts_hidden": false }, { "id": "3996898910693261359", "shortcode": "Dd31mH_BIAv", "url": "https://www.instagram.com/reel/Dd31mH_BIAv/", "owner": { "id": "35083438009", "username": "living.withsara" }, "taken_at": 1790687549, "taken_at_iso": "2026-09-29T13:12:29.000Z", "caption": "the most important day of the year🫶\n\n#fyp #nationalcoffeeday☕️ #nationalcoffeeday #coffee #latterecipe", "media_type": "reel", "pinned": false, "thumbnail_url": "https://instagram.fsjc1-4.fna.fbcdn.net/v/t51.71878-15/828443416_1756858129566676_6625939589098108439_n.jpg", "media": [ { "id": "3996898910693261359", "type": "video", "image_url": "https://instagram.fsjc1-4.fna.fbcdn.net/v/t51.71878-15/828443416_1756858129566676_6625939589098108439_n.jpg", "video_url": "https://instagram.fsjc1-4.fna.fbcdn.net/o1/v/t2/f2/m86/AQNQ84Dk32MfIs7857-djyxgkThJtejegVOuWaQvb59HNvg7yiYrJaAouDruIMK1SzNIksJaAMfjGZB4CXX3r48jVL6pJKeygWEhWbk.…", "width": 1080, "height": 1920, "video_duration": 11.566 } ], "likes": 3, "comments": 19, "shares": 1532, "reposts": 325, "views": 662206, "saves": 437, "video_duration": 11.566, "counts_hidden": true } ], "next_cursor": "c1.ryg6VkAgkE2BcPyGM0q6ADwLG1KAGWvXyxXcleap6rtdnm6USXXD4rRRujLUjticHxS2vixe2jbdlG4LggGvIE1ISp6sYLXI6XWcb66UIrM_RMPDKCUhQylnCgNoMsPrfzM", "has_more": true } ``` A real answer, shortened: lists are cut to two items and long texts to 160 characters. ## Price and freshness A call takes 1 request. Free requests are spent first, then your balance. The [pricing](https://storiesfly.com/developers/pricing) page has the rates. Answers are kept for up to 30 minutes. Asking again inside that time returns the same answer and takes 1 request again. Page size follows Instagram and varies by endpoint. ## Errors A failed call answers with an HTTP status and a body `{error, code}`. These are the codes this endpoint gives. [Errors and what is charged](https://storiesfly.com/developers/docs#errors) covers all of them. | Status | Code | When | | --- | --- | --- | | `400` | `bad_request` | A parameter is missing or wrong. `fields` lists the names. Free. | | `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. | | `402` | `credits_exhausted` | The free requests and the balance are used up. Top up in the [dashboard](https://storiesfly.com/developers/dashboard). Free. | | `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. | | `429` | `rate_limited` | More requests in a second than your level allows. Wait for the `Retry-After` header. Free. | | `500` | `internal_error` | A fault on our side. Retry shortly. Refunded. | | `503` | `upstream_unavailable` | Our side failed or timed out. Retry shortly. Refunded. | ## Questions about this endpoint ### What does it return? Reels for a text, with caption, video link, time and counts, in the same fields as [user/reels](https://storiesfly.com/developers/docs/user-reels). ### How do I read all the reels that match? Send the `next_cursor` of the answer back as `cursor` for the next page, and stop when `has_more` is `false`. Each page takes 1 request. A cursor works only on the endpoint that returned it. ### Does q have to be a hashtag? No. `q` is any text of 1 to 100 characters. For the reels under one hashtag use [hashtag/posts](https://storiesfly.com/developers/docs/hashtag-posts) with `sort=reels`. ## Related endpoints - [GET /v1/search/top](https://storiesfly.com/developers/docs/search-top): The top posts for a text - [GET /v1/search/users](https://storiesfly.com/developers/docs/search-users): Find accounts by name or username - [GET /v1/user/reels](https://storiesfly.com/developers/docs/user-reels): Reels with captions, video and play counts - [GET /v1/search/hashtags](https://storiesfly.com/developers/docs/search-hashtags): Find hashtags, with their post counts ## Links - [This page on the site](https://storiesfly.com/developers/docs/search-reels) - [Instagram data API](https://storiesfly.com/developers): what the API is and what it returns - [Pricing](https://storiesfly.com/developers/pricing): rates, examples and billing rules - [Documentation](https://storiesfly.com/developers/docs): quick start, authentication, errors and every endpoint - [OpenAPI file](https://storiesfly.com/openapi.json): the whole API in one file - [API dashboard](https://storiesfly.com/developers/dashboard): get a key and top up - [Changelog](https://storiesfly.com/developers/changelog): what changed and when