Search endpoint

Music search API

Finds audio tracks by title or artist (q), with length, cover and audio link. Pass next_cursor back as cursor for the next page.

GEThttps://storiesfly.com/api/v1/search/music

Price 1 request
Answers up to 1 hour old

Get 100 free requests All endpoints

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, or in the apiKey option of the npm client.

curl "https://storiesfly.com/api/v1/search/music?q=coffee" \
  -H "X-Api-Key: sf_live_your_key"

const res = await fetch(
  "https://storiesfly.com/api/v1/search/music?q=coffee",
  { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } }
);
const data = await res.json();

import os
import requests

r = requests.get(
    "https://storiesfly.com/api/v1/search/music",
    params={"q": "coffee"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()

import { StoriesFly } from "storiesfly";

const sf = new StoriesFly({ apiKey: process.env.STORIESFLY_KEY! });

// The first page. The answer has next_cursor and has_more.
const data = await sf.search.music({ q: "coffee" });

// Every page, up to 4. Each page is charged as one call.
for await (const page of sf.paginate(sf.search.music, { q: "coffee" }, { maxPages: 4 })) {
  console.log(page.tracks.length);
}

Example response

200 OK · X-Units-Charged: 1

{
  "tracks": [
    {
      "id": "532059980565989",
      "title": "Coffee",
      "artist": "beabadoobee",
      "duration": 126.824,
      "cover_url": "https://scontent-iad6-1.cdninstagram.com/v/t39.30808-6/424786500_1021000328996810_2786139399274716171_n.jpg",
      "audio_url": "https://scontent-iad6-1.cdninstagram.com/o1/v/t2/f2/m69/AQND5YTsAcGy_Y-rxaVMwRxfcBnUjMsSaw6x-KnDZWJeiJRz0wFWSBxaWDZD15xiXHMjSTdsQENt4-Y6rec0XJwe.mp4"
    },
    {
      "id": "1467739367151376",
      "title": "Espresso",
      "artist": "Sabrina Carpenter",
      "duration": 175.453,
      "cover_url": "https://scontent-iad6-1.cdninstagram.com/v/t39.30808-6/432991226_90027831925461_1955188252301264968_n.jpg",
      "audio_url": "https://scontent-iad6-1.cdninstagram.com/o1/v/t2/f2/m69/AQMexVGe3_yd8hPJCLWN0ScdXRa7mH3x-qJSWVftJz_Cc4cQI2MunEVoTVpzl025KSCKkURwibMDAqwg_Rs-fR68.mp4"
    }
  ],
  "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 page has the rates.

Answers are kept for up to 1 hour. 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 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. 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.

FAQ

Questions about this endpoint

What does each track hold?

Its id, title, artist, duration in seconds, cover_url and audio_url when Instagram gives one.

How do I read all the tracks 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.

How do I get one track?

track returns a single track for its id.

Your first 100 requests are on us

Get my API key Read the docs