### 1. Set the limit of audio streams Set the maximum limit of concurrent audio streams and make a payment [on the API Dashboard](https://dashboard.audd.io/). (If you want to test the service for free, reach out: api@audd.io.) After this, you can interact with the API using a web interface, which allows adding, removing, and updating streams, as well as downloading the last 40 music recognition results. (If you don't set up a server for callbacks, set the callback URL to `https://audd.tech/empty/` for the interface to work properly.) **Please note that all the API requests require the api_token from the Dashboard to be specified as either the query parameter or the POST field**. So just send it in all the requests as `api_token`. If you change the limit later, the unused amount of time will be applied as a discount.

### 2. Set the URL for callbacks ```text https://api.audd.io/setCallbackUrl/ ``` Set the URL for callbacks using the `setCallbackUrl` API method. You can change the URL at any time using this method. Callbacks are the requests with recognition results our servers will send to your server. (Please set the callback URL to `https://audd.tech/empty/` or other URL that responds 200 OK if you don't have a server for callbacks and want to use [longpolling or the no-code widget](#longpoll-1)).

### 3. Add the streams ```text https://api.audd.io/addStream/ ``` Add the streams using the `addStream` API method. By default, we will send new results after songs end playing. See the `callbacks` parameter description if you want to get the results when songs start playing. By default, callbacks are sent after the song ended playing and contain the total streamed time of the song. Set this parameter to before, if you want to receive the callbacks as soon as a song starts playing (instead of when it finishes). Note that with callbacks=before, you won't receive the total played time in the callbacks.

:::info As the URL of the audio stream, you can simply send the URL of a stream, like *https://npr-ice.streamguys1.com/live.mp3*. We support most of the stream formats, including DASH, Icecast, HLS, m3u/m3u8. We also natively support Twitch broadcasts and YouTube live streams, and you can send twitch:\[channel name], youtube:\[video id], and youtube-ch:\[channel id] as the URL - like *twitch:monstercat* for [twitch.tv/monstercat](https://www.twitch.tv/monstercat), *youtube:5qap5aO4i9A* for [youtube.com/watch?v=5qap5aO4i9A](https://www.youtube.com/watch?v=5qap5aO4i9A), or *youtube-ch:UC3zwjSYv4k5HKGXCHMpjVRg* for the current live stream on [youtube.com/channel/UC3zwjSYv4k5HKGXCHMpjVRg](https://www.youtube.com/channel/UC3zwjSYv4k5HKGXCHMpjVRg). :::

### 4. Receive the results #### Using callbacks Receiving the results in callbacks is the recommended method. Callbacks will be sent to the specified URL as a JSON structure in the POST payload. The format is below. You'll receive callbacks with results and notifications. - The results contain the identified songs. - Notifications are information about problems with the streams. If something happens to an audio stream, we'll let you know by sending a notification so you can fix the stream or change its URL. There are 3 codes: `0` (which means that everything's fine), `650` (which means that we can't connect to the stream) and `651` (which means that we don't receive any music from the stream, only white noise). Notifications also contain the time of sending.

If your server doesn't respond to the callbacks with the 200 OK status or we can't connect to your server, we'll put the callbacks in a queue. When your server is back online, we'll gradually send all of the backlog. We have a rate limit for the requests we're sending: if you have fewer than 500 streams, you won't receive more than 3 callbacks per second (with a [burst size](http://en.wikipedia.org/wiki/Token_bucket) of 15). **Contact us to receive ISRCs, UPCs and other additional metadata (e.g., from Apple Music, Spotify, MusicBrainz).** Note that for uploaded catalogs, you'll only receive the unique track ID you sent when you uploaded the matched song; other details won't be available. #### LongPoll You can use long polling instead of or together with receiving callbacks. See the [LongPoll section](#longpoll-1) for more info. For it to work, if you're not planning to receive callbacks, set the callback URL to `https://audd.tech/empty/` using the web interface. (You have to have some callback URL, or you won't be able to retrieve results using long polling.) #### Manually download results This is not recommended, but the last 40 results should usually be available for download using [our web stream management interface](https://audd.io/streams/). For this to work, if you're not planning to receive callbacks, set the callback URL to `https://audd.tech/empty/` using the web interface.

### `POST` Get the current callback URL ```text https://api.audd.io/getCallbackUrl/ ``` Use the `getCallbackUrl` method to get the current callback URL. You can always change it with the `setCallbackUrl` method.

### `POST` Get all the streams ```text https://api.audd.io/getStreams/ ``` Use the `getStreams` method to get all the streams the music is being recognized from.

### LongPoll In addition to callbacks, you can use HTTP longpolling to get new results from any number of clients without having to spin up a web server or have a static IP. Please use the longpolling after setting a working callback URL using the [setCallbackUrl](#2-set-the-url-for-callbacks) method; ensure that the callback URL responds with the `200 OK` HTTP status when it receives requests with callbacks. If you don't have a server that can return 200 OK to POST requests, use `https://audd.tech/empty/`. The long poll address is `https://api.audd.io/longpoll/`. As the subscription category, use the `longpoll_category` field from the [/getStreams](#post-get-all-the-streams) response, or calculate the first nine symbols of `MD5(MD5("your api_token")+"radio_id")`. You can share the categories with your clients or users, but please don't include your API tokens in the client-side software. If you're making the long poll requests manually, here's an example of a LongPoll URL: `https://api.audd.io/longpoll/?category=92b1cc7f0&timeout=50&since_time=1652123144400`. When you receive a response containing the `timestamp` field, use it as the updated `since_time` for the new request. We've implemented long polling clients in our [Golang library](https://github.com/AudDMusic/audd-go) and [Twitch extension (JS)](https://github.com/AudDMusic/twitch-extension). :::tip HTML Widget You can also use our widget, `https://widget.audd.tech/?ch=-92b1cc7f0&background&history&shadow`. It's based on the Twitch extension's frontend and shows the last recognized song as well as the history (if you want it to show the history). Use the longpoll category with "-" before it as the `ch` URL parameter. You can also use the URL parameters to get the look you want, e.g. `https://widget.audd.tech/?ch=-92b1cc7f0&black-font`. ::: You can disable the Long Poll for your streams by adding "disable-lastsong=true" as a parameter to your callback URL (i.e., add `?disable-lastsong=true` or `&disable-lastsong=true` to the URL).